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

[Didier Remy <Didier.Remy@inria.fr>]

My own little comment on comments...

I also wish that the syntax of documentation should remain simple to
understand and visually light, so that the commented code can be read and
writen, directly! without yet another tool...

However, I am worried if this were to rely on indentation. I think that this
is a heavy contraint put on programmers (every one has his own style).
Moreover, this will force all automatic indentation tools (e.g. the
emacs-mode etc.) to understand the meaning of indentation *perfectly* so as
not to break them. This makes these tools very fragile.  Note that today,
these tools only change the presentation, and at worse, there produce a bad
taste indentation but never *loose* information. 

Also, I was taught to believe that relying on white space/tabulations/blanks
for the meaning was awful backward technology (see the \t in Makefiles...).
Why should this not apply to the ``semantics of comments''? 

Overall, I find Jérome's suggestion to use (** aaa *) and (* aaa **) to
indicate placement visually light while it seems to providing *all* the
flexibility that people are calling for: placement should either be before
or after the element, but explicit.

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