[PPL-devel] Devref documentation.

[Enea Zaffanella]

I just started having a look at the various warnings issued by doxygen 
when we compile the devref manual, in order to see if they are due to 
doxygen bugs or to our rather shallow understanding of this 
documentation tool: I strongly believe that we have a mix of the two 
situations.

I will try and produce a few bug reports to be sent to the doxygen 
mailing list ... but here I would like point out a few (possible) 
problems taht are our fault.

1) Upgrading the doxygen configuration files.

Whenever we move to a newer doxygen release, we should upgrade ALL of 
our doxygen configuration files by issuing commands like:

  # doxygen -u <config-file>

This will save the old config file in <config-file>.bak and produce a 
new configuration file, including all the settings of the old one and 
the default values for those config variables that were not used in the 
previous release. Now, I am (we are?) using doxygen 1.2.14, but the 
configuration files in the repository have been produced by using 
doxygen 1.2.6, which is an old release.

The annoying problems when using doxygen -u are:
- our comments in the config. files will be stripped out and replaced by 
the standard comments (minor problem);
- by making a diff, I noted that the automatically generated new config 
files have a lot of trailing white spaces (as well as a few lines that 
are too long).


2) Multiple detailed description blocks.

As far as I can see, doxygen is not able to collect and merge togheter 
multiple description blocks. It will consider just one of them (th elast 
one, I guess). Usually, we have been careful to avoid such a situation, 
except when we wanted to include a particular (non-friend) function in 
the documentation of a class by using the special command \relates 
<class>. Since this command seems not to work properly with brief 
description, we were writing two detail description blocks, one just 
after the brief description (which was including the \relates command 
and nothing else) and one before the actual function definition (without 
the \relates command). The net result was the doxygen warning:

   Warning: no matching file member found for ...

Because (when processing the second comment block) doxygen was not able 
to find a matching declaration (he had no \relates and it was therefore 
looking in the wrong place). The solution is to place the \relates 
command in the (one and only) detailed description block that goes 
before the function _definition_.

3) The use of the flag PPL_DOXYGEN_INCLUDE_IMPLEMENTATION_DETAILS

We were using this flag without any need a couple of times (in Row.cc 
and SatRow.cc). Basically, this flag should never be used in 
*.inlines.hh and *.cc files, since all the member functions (and the 
functions labelled by \related) of an undocumented class will NOT appear 
in the user manual.


Now going on checking if there are other kinds of doxygen warnings.
I will also start to implement some of the above changes.

Enea.