Re: [Caml-list] Documentation tools

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

I'd like to add one small point to the discussion of interface
documentation tools:

Being able to quickly get to texinfo files, man pages, or html docs for
interfaces is great, but there is another way that is often even quicker,
especially for the interfaces in the very project you're working on at
the moment: just read the source!  No matter how fancy our programming
environments and support tools become, we're still going to spend a lot
of time dealing directly with source files for interfaces -- not just
writing, but reading them.  

So I would not like to see us decide on a documentation tool that
requires *every* entry in every interface file to be annotated with some
kind of heavy markup like a big pile of html/docbook tags.  A small
amount of extra cruft in interfaces is acceptable, but please let's not
make all our .mli files totally unreadable for the sake of generating
fancy docs.

This is one thing that I think ocamlweb gets right: documentation
comments can usually be just straight text, with embedded ML fragments
enclosed in [...] so that the tool knows to change the font (and a more
sophisticated tool might know to cross-reference known identifiers,
etc.).  I hope whatever tool the OCaml community chooses or designs will
maintain this philosophy.

   -- B

-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr