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

["Benjamin C. Pierce" <bcpierce@saul.cis.upenn.edu>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 2417 bytes --]

OK, just one more comment on comments from me too...

> 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''? 

The worst thing wrong with this convention in Make is that \t and eight
spaces look the same but mean different.  Nothing like that is being
proposed here.  

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

Note that it's also a bit more error prone: if I move a comment from
after to before but forget to change its funny marker, it will get
attached to the wrong place.

More generally: there is not going to be a perfect solution to this
problem -- any solution is going to be a tradeoff between 
   - desire of people who work directly with the code to keep it readable
   - desire of documentation writers to do fancy arbitrary stuff easily
   - simplicity of implementation
   - needs of other tools like prettyprinters

All I'm saying is that I care a *lot* more about #1 than any of the
others.  

But, having expressed my opinion about it, I'll be quiet now -- the
OCamlDoc designers and implementors [*] have done a great job with what's
there already, and I'm sure that, whatever the details of the final tool
turn out to look like, it will do the job just fine.

        B

[*] I get the impression that several people at INRIA are talking about
it and Maxence is taking the lead on the detailed design and
implementation -- is that right?

-----------------------------------------------------------------------------
BENJAMIN C. PIERCE
Associate Prof., Computer & Information Science        bcpierce@cis.upenn.edu
University of Pennsylvania                                    +1 215 898-2012
200 South 33rd St.                                       Fax: +1 215 898-0587
Philadelphia, PA 19104, USA                http://www.cis.upenn.edu/~bcpierce
-----------------------------------------------------------------------------





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