Original bug ID: 3698
Reporter: administrator
Status: acknowledged
Resolution: open
Priority: normal
Severity: feature
Category: ocamldoc
Tags: junior_job
Monitored by: @Chris00

Bug description

Full_Name: Christophe TROESTLER
Version: 3.08.3
OS: Debian GNU/Linux
Submission from: nat2.umh.ac.be (193.190.193.2)

Feature wish:

The following changes to ocamldoc would be nice I think:

• Do not add extra blank lines when {[ and ]} are on a line by themselves. This
  is because if the .mli is read directly, it is natural to use the following
  style

  Simple Example:
  {[
  cgi # output # output_string "Hello world!\n";
  cgi # output # commit_work()
  ]}

but that does not look nice when "compiled" to HTML.

• A small extra vertical space between the @param options will improve
  readability. See e.g.
  http://ocaml-cgi.sourceforge.net/netcgi/Netcgi-cgi.html#3_Outputting

• Accepting the syntax @raise [xxx] may be useful: e.g.
  @raise [Failure "int_of_string"]

• Documenting records on the side of them is only useful when the documentation
  of the each member of the record is short. Otherwise I believe it would be
  better to document them as one does for functions in a module (with proper
  identation).
  See: http://ocaml-cgi.sourceforge.net/netcgi/Netcgi.html#2_Theenvironmentofarequest

Also on can leave the documentation "brackets" (* *) in typewriter face but the
content should use the usual documentation face. Otherwise, that leads to odd
things as with:

type a = {
a1 : int option; (** The is the member [a1]. The value
- [None] represent...
- [Some i] means that ... *)
}

• It would be nice to be able to document variants in the same way records are.
  Example:

(** HTTP status codes from RFC 2616. )
type status =
(* 2xx: (successful) )
[ Ok (** 200 *) | Created (* 201 )
| Accepted (** 202 *) | Non_authoritative (* 203 )
| No_content (** 204 *) | Reset_content (* 205 *)
| Partial_content (** 206 *) (** 3xx: (redirection) *) | Multiple_choices
| Moved_permanently | Found
| `See_other
...