[Caml-list] Re: About documentation tools

[Markus Mottl <mottl@miss.wu-wien.ac.at>]

On Wed, 09 May 2001, David Mentre wrote:
> ocamlweb intents to be a tool to document source code as Knuth's WEB
> tool. In other words, it's more for internal code documentation than
> for user manual and reference guide.

It can also be used to extract information about interfaces. The nice
thing about it is that it allows you to fully exploit the power of Latex
(and therefore Hevea). I think it's a good idea to support such features
if one wants to have flexible ways of generating documentation.

> the tool used by the Caml team is specific and not ready for a public
> release, i.e. some shortcomings are solved in ad-hoc manner.

But it wouldn't hurt either to make it available as alpha software on
some CVS-server, would it? Maybe some voluntary hero (not me ;) would
go about making it "ready for public use"...

> But I agree that a recommended documentation tool would be a plus.

I still see a lack of "social" standard tools. Documentation tools
are one thing, packaging tools another. Wouldn't this be exactly the
right thing that the new OCaml-consortium would want to fund? - 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.

How are things developing in the Consortium? Are there already plans to
fund specific projects, possibly of this kind?

> It does not mean that such a tool should be very elaborated. The
> simpler, the better.

I find ocamlweb fairly easy to use (not really much more difficult than
your tool, I think). It still gives you the option to drop to Latex
if required.

> And I also think that such a tool should be close to standard tool
> in other languages, mostly javadoc. It would help the transition from
> other languages (and multi-language developments).

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.

Best regards,
Markus

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr