0003698: Improvements to ocamldoc

View Issue Details [ Jump to Notes ]

[ Issue History ] [ Print ]

Project

Category

View Status

Date Submitted

Last Update

0003698

OCaml

OCaml general

public

2005-06-22 11:38

2005-06-22 16:05

Reporter

administrator

Assigned To

Priority

normal

Severity

feature

Reproducibility

always

Status

acknowledged

Resolution

open

Platform

OS Version

Product Version

Target Version

Fixed in Version

Summary

0003698: Improvements to ocamldoc

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
  ...

Issue History
Date Modified	Username	Field	Change
2005-11-18 10:13	administrator	New Issue

Relationships

Notes
There are no notes attached to this issue.