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

[Xavier Leroy <xavier.leroy@inria.fr>]

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