Re: Lua Digest, Vol 63, Issue 4

["Frans Slothouber" <frans.slothouber@...>]

On 15/08/07, Ross Berteig <Ross@cheshireeng.com> wrote:
> Sometime on Wed, 15 Aug 2007, Frans Slothouber wrote:
> >To create the latter tools like DoxyGen, ROBODoc, JavaDoc, etc
> >[snip]
> >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
> >the source
> >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.

Links to functions, object, and other artifacts are possible with Word/TeX/...
ROBODoc can dump the documentation for every artifact in a individual
html file with an unique and identifiable name.
It is possible to create hyperlinks to those files.

DoxyGen seems to use a similar scheme.

Creating links the other way around is more difficult of course.

> For mid-sized projects I have
> used that technique fairly effectively.

It is possible but I would argue inconvenient.
ROBODoc allows you to add overview documentation too.
These too are big comment headers, they can be in any file.
You can even indicate chapter/section levels.
But writing several pages of documentation in plain ascii is
pretty limiting.   Even more so when you want to add equations
and tables.

Having full wiki-like formatting feature would be handy in this case
(wikipedia documentation looks decent).
ROBODoc has some wiki-like formatting, but it is limited.

Maybe programs should be written as Wiki's.... both source and
documentation.

> 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.

Graphviz is a wonderful tool.  But the dot language can be difficult to use.
Mainly because dotty decides what the final layout it and it difficult
to force dotty to move than one element in just that right spot.

But it is a step in the right direction.

> 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.

Yup.  I had the same experience with a 500,000 line C project
documented with ROBODoc.  Most artifacts are documented
but the information content is minimal.
Same with a similar size C++ project done with DoxyGen.

The problem seems that after a while the documentation turns
in to write-only stuff.  Programmers write it but never reread it
and therefore not improve it and add to it.

The question is, is this because they know the information by heart after
a while, or because the resulting documentation not easy to use in the first
place?

Still, it much better than the alternative of not putting it in
the source code but in a separate document. That's a guaranteed
recipe for out-of-date documentation.

> 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.

Most definitely!

Have fun,
Frans Slothouber.