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 OAA20480; Sun, 14 Oct 2001 14:50:06 +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 OAA20456 for ; Sun, 14 Oct 2001 14:50:06 +0200 (MET DST) Received: from mail.cs.uu.nl (sunset.cs.uu.nl [131.211.80.32]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f9ECo5D09565 for ; Sun, 14 Oct 2001 14:50:05 +0200 (MET DST) Received: from silvester.cs.uu.nl (silvester.cs.uu.nl [131.211.80.119]) by mail.cs.uu.nl (Postfix) with SMTP id 00EE7451A; Sun, 14 Oct 2001 14:50:04 +0200 (MET DST) Received: by silvester.cs.uu.nl (sSMTP sendmail emulation); Sun, 14 Oct 2001 14:50:04 +0200 Date: Sun, 14 Oct 2001 14:50:04 +0200 From: Frank Atanassow To: bcpierce@cis.upenn.edu Cc: Francois.Pottier@inria.fr, caml-list@pauillac.inria.fr Subject: Re: [Caml-list] Re: [Caml-announce] OCamldoc Message-ID: <20011014145004.B3057@cs.uu.nl> References: <20011012151319.A16917@pauillac.inria.fr> <19083.1002973746@saul.cis.upenn.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <19083.1002973746@saul.cis.upenn.edu>; from bcpierce@saul.cis.upenn.edu on Sat, Oct 13, 2001 at 07:49:06AM -0400 Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk Benjamin C. Pierce wrote (on 13-10-01 07:49 -0400): > (I'm glad we've had > so much discussion about it, though, because now people will think twice > before proposing *more* funny characters to go in comments... :-) Whoa, hold on there! You haven't heard my proposal yet: I think we should have documentation comments of the form (* ... *) where r1 and r2 are REGULAR EXPRESSIONS which match the part of the source that the documentation applies to. This covers all the possible cases, plus MANY MORE. Not only can you have the comment BEFORE, on THE SAME LINE and AFTER but also IN THE MIDDLE of your code! Just think of all the possibilities for SELF-EXPRESSION and CUSTOMIZATION. No more WORRIES or CONSTERNATION about finding the right spot: just put it ANYWHERE. Some people might argue against this because it is overly complicated, and you would have to change the regular expressions if you move the comment, but THAT IS WHAT O'REILLY BOOKS AND PROGRAMMABLE EDITORS ARE FOR! In fact, I can imagine a whole INDUSTRY growing out of this. Think of the BUSINESS OPPORTUNITIES, an entire NEW MARKET. I urge you ALL to GET IN ON THE GROUND FLOOR NOW, before you MISS OUT!!!! [I wonder how many people's spam filters got triggered on this... ] Seriously though, my preferences are, in order: 1) only (** ... *) comments preceding the code, as in Java; 2) Benjamin's indentation-significant style 3) Jerome's (** ... *) and (* ... **) comments My reasoning is that 1) is best because, since this is a new feature and no one is forced to use it, it's not unreasonable to expect people to stylize their documentation comments according to a single, new convention which is, anyway, familiar from Java. 2) is better than 3) for the reason Benjamin mentioned already: if you move the comment, you have to remember to change the asterisks, and that seems pretty error-prone to me. Someone argued that significant indentation is a burden for source preprocessors as they need to preserve the indentation exactly. I don't find this so convincing since preprocessor _output_ is usually not meant for human eyes at all, but rather for the compiler. Usually you will run CamlDoc on the preprocessor _input_, right? A preprocessor could even just convert all the documentation comments to regular comments if it didn't want to produce misleading output. -- Frank Atanassow, Information & Computing Sciences, Utrecht University Padualaan 14, PO Box 80.089, 3508 TB Utrecht, Netherlands Tel +31 (030) 253-3261 Fax +31 (030) 251-379 ------------------- 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