Re: [Caml-list] Re: [Caml-announce] OCamldoc

[Jerome Vouillon <jerome.vouillon@inria.fr>]

On Tue, Oct 09, 2001 at 08:26:48AM +0200, Francois Pottier wrote:
> I would consider it more consistent to always require the comment to
> precede the element. The purpose of the current convention concerning
> record fields and data constructors seems to be to encourage people
> to write comments that fit on the remainder on the line, which is bad
> practice anyway.

You don't have to put the comment on the same line.  You can write:
    type t =
        C1 of int
            (** constructor 1 *)
      | C2 of float
            (** constructor 2 *)

Besides, I think it is usually more readable to put the comment after
the element.  Indeed, you often search for an element (by name), and
then read the corresponding comment.  So, for instance, I prefer this:
    val to_list: 'a array -> 'a list
            (* [Array.to_list a] returns the list of all the elements
               of [a]. *)
    val of_list: 'a list -> 'a array
            (* [Array.of_list l] returns a fresh array containing the
               elements of [l]. *)
    val iter: f:('a -> unit) -> 'a array -> unit
            (* [Array.iter f a] applies function [f] in turn to all
               the elements of [a].  It is equivalent to
               [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
to this:
    (** [Array.to_list a] returns the list of all the elements of [a]. *)
    val to_list: 'a array -> 'a list
    (** [Array.of_list l] returns a fresh array containing the elements
        of [l]. *)
    val of_list: 'a list -> 'a array
    (** [Array.iter f a] applies function [f] in turn to all
        the elements of [a].  It is equivalent to
        [f a.(0); f a.(1); ...; f a.(Array.length a - 1); ()]. *)
    val iter: f:('a -> unit) -> 'a array -> unit

What about the following syntax?
- The comment is before the element:
      (** fun 1 *)
      val f : t
      (** fun 2 *)
      val g : u
- The comment is after the element:
      val f : t
        (* fun 1 **)
      val g : u
        (* fun 2 **)

-- Jerome
-------------------
Bug reports: http://caml.inria.fr/bin/caml-bugs  FAQ: http://caml.inria.fr/FAQ/
To unsubscribe, mail caml-list-request@inria.fr  Archives: http://caml.inria.fr