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

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

> Personnaly, i would be very strongly against using indentation to define if
> the stuff is before or after, after all, not everyone wants to indent things
> the same way.

Is there *anyone* that wants to write

      (* Comment for f *)
  val f : t
      (* Comment for f *)
  val g : t'

?  These are the only people that should be unhappy with my proposed rule.

> The (*< and (*> idea seems good and very intuitive. what is the reproch
> against it you have ?

I don't want all sorts of funny characters lying around in my comments
when I read/write .mli files.  It's very easy for this sort of tool to
get out of control and turn the source files into full-blown markup
language that can be used to produce all sorts of cool and powerful
effects in the docs, but that looks ugly when you read it in the text
editor.  So I'm resisting taking even one step onto the slippery slope.

What I'd really like to have is
   - A rule for distinguishing "documentation comments" from all other
     comments 
   - A way of marking "OCaml stuff" when it occurs inside comments,
     e.g. by enclosing it in square brackets, so that the doc tool knows
     to set it in a different font (and can maybe try to parse it, find
     identifiers, index, hyperlink, etc.)
   - That's all!

>From the OCamlDoc manual, I see that the present design of the tool does,
in fact, go quite a few steps further than the point where I could have
stopped.  Instead of putting in all these little markup commands, I would
have preferred a single marker meaning "escape to raw hevea [or whatever]
and let me do whatever I want at this point."  This provides all the
power that one could ever need, but discourages people from using it more
than occasionally -- a Good Thing.  However, I think the current design
is actually a pretty reasonable compromise between what I want and what
other (more feature-loving :-) people might like.  It allows me to
produce *reasonable* docs with *simple* (and not very ugly) mechanisms,
while allowing others to produce pretties docs at some cost in ugliness
of the sources.  Please let's try to keep this property!

     Benjamin



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