 |
lua-l archive |
|
|
||
|
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 hardto build from little pieces of documention scattered all over the sourcecode. 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 browser.
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/