[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Lua Digest, Vol 63, Issue 4
- From: Ross Berteig <Ross@...>
- Date: Wed, 15 Aug 2007 14:19:04 -0700
Sometime on Wed, 15 Aug 2007, Frans Slothouber wrote:
To create the latter tools like DoxyGen, ROBODoc, JavaDoc, etc
are well suited. Because they keep the documentation of these
artifacts close to the artifacts there is a much higher chance they
are kept up to date.
To create a big picture document these tools are not at all suited.
Big picture documents need a story line. A story line is very hard
to build from little pieces of documention scattered all over
code. Big picture documents also need figures and diagrams. These
are also hard to make in those tools.
Doxygen has a cryptic but functional mechanism (as does JavaDoc
as well) for including overview documentation in a project. You
can include any number of additional text files that use Doxygen
tags to create additional document pages. Syntactically they are
one giant C comment, but need not be included by any C source
file or otherwise involved in the program's build process. One
advantage of doing this over a separate Word (or TeX or...)
document is that you can link to specific functions, objects,
globals, etc., and vice-versa. For mid-sized projects I have
used that technique fairly effectively.
If you have the Graphviz tools available
(http://www.graphviz.org/), Doxygen will use them to draw a
variety of figures automatically, and you can also include
figures of your own written in its dot language. Graphviz works
well for describing object relationships, program flow, time
lines, and even memory layout. Of course there are still times
where there is no replacement for a photograph, but I haven't
tried to figure out how to get Doxygen to do that.
One place these mechanisms have trouble is documenting something
like a lua module implemented in C. The natural location for the
documentation of the foo.bar() function is right at the
implementation of static int foo_bar(LUA_STATE *L) but Doxygen
wants the comment block to reflect the C API which bears no
relationship at all to the functionality that it implements for
the Lua caller.
And both the preliminary design documents (not to mention the
project proposal) and end user documents (user guide, reference,
installation, trouble-shooting, etc.) are way outside the scope
of what is possible with something like Doxygen.
All that said, I will concur that all too often there is no
actual attempt made to provide any documentation beyond the
minimal amount required for each structure, object, function,
and method to make the warnings go away. The result is the kind
of raw reference that is really little more than a decent source
One of the things that impressed me right away about Lua was the
high quality of its documentation, including both the reference
manual and the How-To information in PiL. We should all aspire
to produce products that are as well and as clearly documented.
Ross Berteig Ross@CheshireEng.com
Cheshire Engineering Corp. http://www.CheshireEng.com/