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 NAA20813; Tue, 9 Oct 2001 13:28:30 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: from concorde.inria.fr (concorde.inria.fr [192.93.2.39]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id NAA20815 for ; Tue, 9 Oct 2001 13:28:29 +0200 (MET DST) Received: from inria.fr (santenay.inria.fr [128.93.8.59]) by concorde.inria.fr (8.11.1/8.10.0) with ESMTP id f99BSS526272; Tue, 9 Oct 2001 13:28:29 +0200 (MET DST) Message-ID: <3BC3343C.8040704@inria.fr> Date: Tue, 09 Oct 2001 13:30:36 -0400 From: Maxence Guesdon User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:0.9.3) Gecko/20010808 X-Accept-Language: fr, en MIME-Version: 1.0 To: Jerome Vouillon CC: Francois Pottier , caml-list@inria.fr Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc References: <3BC218CA.9060008@inria.fr> <20011009082648.A14690@pauillac.inria.fr> <20011009122043.A18529@pauillac.inria.fr> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk > > 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