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 MAA19082; Tue, 9 Oct 2001 12:20:45 +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 MAA19467 for <caml-list@pauillac.inria.fr>; Tue, 9 Oct 2001 12:20:44 +0200 (MET DST)
Received: from pauillac.inria.fr (pauillac.inria.fr [128.93.11.35])
	by concorde.inria.fr (8.11.1/8.10.0) with ESMTP id f99AKh524123;
	Tue, 9 Oct 2001 12:20:43 +0200 (MET DST)
Received: (from vouillon@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id MAA19458; Tue, 9 Oct 2001 12:20:43 +0200 (MET DST)
Date: Tue, 9 Oct 2001 12:20:43 +0200
From: Jerome Vouillon <jerome.vouillon@inria.fr>
To: Francois Pottier <francois.pottier@inria.fr>
Cc: Maxence Guesdon <maxence.guesdon@inria.fr>, caml-list@inria.fr
Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc
Message-ID: <20011009122043.A18529@pauillac.inria.fr>
References: <3BC218CA.9060008@inria.fr> <20011009082648.A14690@pauillac.inria.fr>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Mailer: Mutt 1.0i
In-Reply-To: <20011009082648.A14690@pauillac.inria.fr>; from francois.pottier@inria.fr on Tue, Oct 09, 2001 at 08:26:48AM +0200
Sender: owner-caml-list@pauillac.inria.fr
Precedence: bulk

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

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