From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (from majordomo@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id PAA16734; Wed, 10 Oct 2001 15:26:43 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: from nez-perce.inria.fr (nez-perce.inria.fr [192.93.2.78]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id PAA16590 for ; Wed, 10 Oct 2001 15:26:42 +0200 (MET DST) Received: from dpt-info.u-strasbg.fr (dpt-info.u-strasbg.fr [130.79.44.193]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f9ADQf101318; Wed, 10 Oct 2001 15:26:41 +0200 (MET DST) Received: (from luther@localhost) by dpt-info.u-strasbg.fr (8.9.3/8.9.3) id PAA03291; Wed, 10 Oct 2001 15:26:24 +0200 Date: Wed, 10 Oct 2001 15:26:24 +0200 From: Sven To: Jerome Vouillon Cc: Francois Pottier , Maxence Guesdon , caml-list@inria.fr Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc Message-ID: <20011010152624.A3177@dpt-info.u-strasbg.fr> References: <3BC218CA.9060008@inria.fr> <20011009082648.A14690@pauillac.inria.fr> <20011009122043.A18529@pauillac.inria.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0.1i In-Reply-To: <20011009122043.A18529@pauillac.inria.fr>; from jerome.vouillon@inria.fr on Tue, Oct 09, 2001 at 12:20:43PM +0200 Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk 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