You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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
...
The text was updated successfully, but these errors were encountered:
Marking at least the stripping of blank space around code blocs as a junior task. A related nicety would be to check whether the whole code block is indented to at least the same level as the opening {|, and in that case remove that level of indentation -- to handle cases like in Cristophe's message above where the whole thing is indented.
Please don't change that again or do once a full and final review to generate properly semantically "classified" html without any br or formatting elements. I can't count the number of times I had to tweak my ocamldoc stylesheet in each of my projects because of whitespace issues after a new release.
This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.
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 ... *)
}
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
...
The text was updated successfully, but these errors were encountered: