[GRASS-dev] Our Doxygen issues

[Vaclav Petras]

Hi,

we recently experienced several errors in Doxygen documentation
generation (e.g. broken contents tree, not generated documentation).
With Doxygen it is sometimes hard to find an error for several
reasons.

Doxygen 1.8 is used server but e.g. Doxygen in Ubuntu 10.04 is only
1.6. (Error/doxygen bug with missing @endcode is only in 1.8, r53078
[1]). So you should download latest release (binary available [2]) to
be sure that everything will work.

Doxygen documentation is to wide for our use so it is hard to study
only things we want to use. And on the other hand, some parts are not
well documented.

Doxygen more or less does not have errors (i.e. it not fails) but some
of the warnings are errors (e.g. more than one \mainpage, r53082 [3]).
In GRASS Doxygen documentation are many warnings and many of them are
really not important but almost everyone means that something is wrong
(e.g. argument not found in the argument list). Finally, some errors
are silently ignored because Doxygen just tries to interpret command
in different way. But it is rare case (no example comes to my mind).

Different errors can appear when you are compiling documentation for
GRASS and different for one part (e.g. explicit references).

But I think that most of the problems can be avoided if we time to
time or after some change check the Doxygen warnings. When you want to
find a warning in Doxygen output it is necessary to redirect stderr to
a file and than apply different filters. Here are some commands I
recently used (common grep nothing extra).

 make htmldox 2> doxyerror.log
 grep -v " are not documented:" doxyerror.log
 egrep -v " are not documented:|is not found in the argument list of|^
 parameter '.*'" doxyerror.log
 egrep -v "is not found in the argument list|are not
documented|parameter '.*'" doxyerror.log | grep ".dox:"

As I remember there were 2200 lines of warning but I reduced it to
1400. It was easier then it looks like [4]. More can be easily done
just pick up the part of the code you know. Sometimes documentation is
there and only function parameters in documentation has wrong names
(fix of one function can reduce the number of warnings by 3 or more).
Sometimes documentation is really missing but it is easy to write I
you know what the function is doing.

If we reduce the number of less important warnings we can find more
important one even without filtering. But now I would recommend to use
filtering (by file name, function name or error type). There important
warnings usually are connected to references and wrong Doxygen
tags/command names.

Doxygen errors are not critical but the broken online programmer's
manual can break GRASS reputation, so please, check Doxygen error
output.

Vaclav


PS: There are several questions how we should use particular features
of Doxygen, e.g. mainpage command and subpages. Feel free to open
discussion.

[1] http://trac.osgeo.org/grass/changeset/53078
[2] http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
[3] http://trac.osgeo.org/grass/changeset/53082
[4] http://trac.osgeo.org/grass/changeset/52600