Re: documentation (Re: Re : [Caml-list] Not Rocket Science)

[Oliver Bandel <oliver@first.in-berlin.de>]

Zitat von Oliver Bandel <oliver@first.in-berlin.de>:
[...]
> IMHO the biggest necessity is better documentation.
> This also holds for a lot of OCaml-libraries, like
> Camlimages and others.

I didn't meant the standard lib...
(...but possibly, because I now know how to use them?)



>
> It's fine to have the documentation showing all
> types and values.
> It's even better to explain, what modules can plugged in in which
> other
> modules, meaning here: which types of the modules in use fit
> together.

With ocamldoc for example it is possible to show
the relations of the modules of a program, and to
show which module uses which other module.
(graphviz-output). This is a quite good idea.

To have such a thing for the way,
modules should/can be plugged together,
determined by the custom types that are provided by the modules,
would enhance readability and understanding of a documentation a lot!

I'm not sure if this should be an additional function for ocamldoc;
possibly one also could create dummy-applications that use modules
in a way, so that plug-in possibilities can be shown with ocamldoc,
when using the graphviz-option. But this are
indirections/detours/workarounds.

Possibly an new, added functionality of ocamldoc or another
application could be used here.

Or is ocamlbuild able to create such stuff?
As I so far didn't used it, maybe someone knows
if it can be used for such documentation-enhancements?


Ciao,
   Oliver