Re: [Caml-list] Re: [Caml-announce] OCamldoc

[Frank Atanassow <franka@cs.uu.nl>]

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

  (*<r1> ... <r2>*)

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... <gulp!>]

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