Re: [Caml-list] Re: About documentation tools

[John Max Skaller <skaller@ozemail.com.au>]

Markus Mottl wrote:

> It's a
> reasonable assumption that Xavier and the others prefer hacking away on
> new compiler features rather than such things and would need engineers
> for more earthly tasks.

	I don't think this is as reasonable as you say.
In principle, an Ocaml module interface should specify semantics.
However, Ocaml doesn't include language constructs to specify
the axioms the interface obeys: they have to be given as comments.

	Some languages, like Eiffel, actually support constructions
for specifying function preconditions.

	So it actually makes sense to allow axioms to be
specifed in a module interface _as part of the language_,
even if it is only a special form of comment containing
vague natural language text.

	I'm not suggesting this, only that Xavier may be more
interested than you think in formalising a documentation
protocol designed to supply the missing information.

> I don't know Java (and therefore javadoc) well enough to judge this
> (maybe at least javadoc is well-designed), but I'd surely argue against
> taking up inferior approaches if we can do things the right way right
> from the start.

	Ocamlweb -- and Javadoc -- are 'inferior' approaches.
A fully fledged literate programming tool is a better solution.
But it requires a 'heavy' committment to literate programming
many are not willing to make. So a more lightweight approach
is a reasonable compromise.

	I note that many Java programmers I have talked to
think Javadoc is one of the best things about Java. :-)
I also note that perldoc has served Perl users well.
Python's doc strings do not work as well. A C++ system I have
worked on used a convention suitable for generating 'man' pages.

	Unlike proper LP tools, these things never generate
enough of the right documentation. But at least they generate
_some_, which is better than none at all. Even though I use
a powerful LP tool, I'd adhere to an ocaml convention,
and I'd also use the standard ocamldoc tool in addition 
to the LP tool I use.

	One comment though: a modern tool must generate
HTML, _directly_. It is not good enough to generate LaTeX,
and then translate it into HTML. Please, I want _one_ tool,
not a long complicated error prone chain to add to my
existing chain :-)

-- 
John (Max) Skaller, mailto:skaller@maxtal.com.au
10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850
checkout Vyper http://Vyper.sourceforge.net
download Interscript http://Interscript.sourceforge.net
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr