Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0003698OCamlOCaml generalpublic2005-06-22 11:382013-07-29 09:56
Reporteradministrator 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityalways
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0003698: Improvements to ocamldoc
DescriptionFull_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
  ...

Tagsjunior_job
Attached Files

- Relationships

-  Notes
(0009965)
gasche (developer)
2013-07-29 07:55

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.
(0009973)
dbuenzli (reporter)
2013-07-29 09:56

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.

- Issue History
Date Modified Username Field Change
2005-11-18 10:13 administrator New Issue
2013-07-29 07:55 gasche Note Added: 0009965
2013-07-29 07:56 gasche Tag Attached: junior_job
2013-07-29 09:56 dbuenzli Note Added: 0009973


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker