This site is updated infrequently. For up-to-date information, please visit the new OCaml website at ocaml.org.

[Caml-announce] OCamldoc
[ Home ] [ Index: by date | by threads ]
[ Search: ]

[ Message by date: previous | next ] [ Message in thread: previous | next ] [ Thread: previous | next ]
 Date: 2001-10-09 (11:28) From: Maxence Guesdon Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc
```>
> 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

I agree that, in .mli files for example, i prefer to have the comment
after the definition, but for consistency between .ml and .mli files,
the comment-before-definition way was chosen.

> 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 **)

I must admit i'd rather keep very simple placement rules.

--
Maxence

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

```