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

[Sven <luther@dpt-info.u-strasbg.fr>]

On Tue, Oct 09, 2001 at 12:20:43PM +0200, Jerome Vouillon wrote:
> 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 **)

Huh, ...

I think this whole thing is largely a personnal preference thing (altough i
myself put commentes before, especially when the function, declaration or
whatever is large). What about a configuration option so people could choose
their mode ?

You could have a :

(*** comment before **)

or a :

(*** comment after **)

At the begining of the files, or use a command line switch ?

Friendly,

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