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 VAA01632; Thu, 11 Oct 2001 21:32:16 +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 VAA01540 for ; Thu, 11 Oct 2001 21:32:15 +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 f9BJWBb23270; Thu, 11 Oct 2001 21:32:11 +0200 (MET DST) Received: (from xleroy@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id VAA01661; Thu, 11 Oct 2001 21:32:11 +0200 (MET DST) Date: Thu, 11 Oct 2001 21:32:11 +0200 From: Xavier Leroy To: bcpierce@cis.upenn.edu Cc: caml-list@inria.fr Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc Message-ID: <20011011213211.B1047@pauillac.inria.fr> References: <8E31D6933A2FE64F8AE3CC1381EEDCE7140166@NT.kal.com> <4066.1002712085@saul.cis.upenn.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <4066.1002712085@saul.cis.upenn.edu>; from bcpierce@saul.cis.upenn.edu on Wed, Oct 10, 2001 at 07:08:05AM -0400 Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk I'm catching up with this lively discussion, which echoes some of the discussions we've had previously among the OCaml developers. I was among the ones who suggested Maxence to stick to a simple, consistent convention, even if it doesn't quite match the comment style that we've used before. Having a convention that is simple to explain and to implement is a big plus. OCamldoc is just a program after all; expecting it to "understand" various pre-existing comment styles is unrealistic. I'm willing to adapt my comment style accordingly (and edit all the .mli files in the OCaml libraries...). Since comments in .ml implementation files naturally come before the definitions, it seemed logical to adopt the same convention for .mli interfaces, In particular, it often happens that we cut-and-paste type definitions between interfaces and implementations, so the comment style must be the same for both. This said, Benjamin's proposal looks appealing: > I.e., *one* kind of (not very) funny comment marker, plus using the > indentation to decide whether the comment binds to the expression before > or after: > > if the comment is on a line by itself, > then if its indentation is the same as the following (non-comment) line > then it goes with the following > else it goes with the preceding > else it goes with the line it's on. That isn't too hard to explain, and matches current practice well. But: languages where indentation is significant (Haskell, Occam, Python) have bad reputation as being 1- harder to parse (for a program), and 2- intolerant w.r.t. cut-and-paste or machine-generated code. 2- is perhaps less of a problem for documentation comments (they are rarely machine-generated :-), but 1- worries me. I've been hacking Lex and Yacc for years, still I do not have the slightest idea on how to take indentation into account in a Lex/Yacc parser... - Xavier Leroy ------------------- 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