From: Sven <luther@dpt-info.u-strasbg.fr>
To: Jerome Vouillon <jerome.vouillon@inria.fr>
Cc: Francois Pottier <francois.pottier@inria.fr>,
Maxence Guesdon <maxence.guesdon@inria.fr>,
caml-list@inria.fr
Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc
Date: Wed, 10 Oct 2001 15:26:24 +0200 [thread overview]
Message-ID: <20011010152624.A3177@dpt-info.u-strasbg.fr> (raw)
In-Reply-To: <20011009122043.A18529@pauillac.inria.fr>; from jerome.vouillon@inria.fr on Tue, Oct 09, 2001 at 12:20:43PM +0200
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
next prev parent reply other threads:[~2001-10-10 13:26 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
2001-10-08 21:21 Maxence Guesdon
2001-10-09 6:26 ` [Caml-list] " Francois Pottier
2001-10-09 10:20 ` Jerome Vouillon
2001-10-09 11:41 ` Eric C. Cooper
2001-10-09 17:30 ` Maxence Guesdon
2001-10-09 14:26 ` Patrick M Doane
2001-10-09 21:12 ` rbw3
2001-10-10 9:19 ` Francois Pottier
2001-10-10 12:35 ` rbw3
2001-10-10 13:26 ` Sven [this message]
2001-10-09 14:46 ` Maxence Guesdon
2001-10-09 8:53 ` Fabrice Le Fessant
2001-10-09 9:42 Dave Berry
2001-10-09 17:26 ` Maxence Guesdon
2001-10-10 13:29 ` Sven
2001-10-14 2:05 ` Mike Leary
2001-10-09 11:40 Dave Berry
2001-10-09 12:14 ` Benjamin C. Pierce
2001-10-09 12:30 Dave Berry
2001-10-10 11:08 ` Benjamin C. Pierce
2001-10-10 13:33 ` Sven
2001-10-10 14:10 ` Jacques Garrigue
2001-10-12 6:23 ` Francois Pottier
2001-10-12 6:50 ` Daniel de Rauglaudre
2001-10-10 15:12 ` Benjamin C. Pierce
2001-10-10 15:25 ` Stefano Lanzavecchia
2001-10-10 15:39 ` Benjamin C. Pierce
2001-10-10 15:44 ` Stefano Lanzavecchia
2001-10-10 18:45 ` Maxence Guesdon
2001-10-10 19:38 ` Benjamin C. Pierce
2001-10-11 7:23 ` Florian Hars
2001-10-12 6:28 ` Francois Pottier
2001-10-12 9:10 ` Sven
2001-10-12 9:39 ` Markus Mottl
[not found] ` <9q7886$2p8$1@qrnik.zagroda>
2001-10-13 9:19 ` Marcin 'Qrczak' Kowalczyk
2001-10-10 15:36 ` Thorsten Ohl
2001-10-10 17:10 ` Patrick M Doane
2001-10-10 19:39 ` Benjamin C. Pierce
2001-10-10 15:25 ` Benjamin C. Pierce
2001-10-10 17:07 ` Patrick M Doane
2001-10-10 17:25 ` Sven
2001-10-11 19:32 ` Xavier Leroy
2001-10-12 8:29 ` Andreas Rossberg
2001-10-12 8:57 ` Didier Remy
2001-10-12 9:27 ` Fabrice Le Fessant
2001-10-12 10:36 ` Benjamin C. Pierce
2001-10-12 13:13 ` Francois Pottier
2001-10-12 17:23 ` Alan Schmitt
2001-10-13 11:49 ` Benjamin C. Pierce
2001-10-13 13:46 ` Jimmie Houchin
2001-10-14 12:50 ` Frank Atanassow
[not found] ` <9q4tft$88t$1@qrnik.zagroda>
2001-10-11 20:13 ` Marcin 'Qrczak' Kowalczyk
[not found] <9q1pg2$85h$1@qrnik.zagroda>
2001-10-10 15:35 ` Marcin 'Qrczak' Kowalczyk
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20011010152624.A3177@dpt-info.u-strasbg.fr \
--to=luther@dpt-info.u-strasbg.fr \
--cc=caml-list@inria.fr \
--cc=francois.pottier@inria.fr \
--cc=jerome.vouillon@inria.fr \
--cc=maxence.guesdon@inria.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox