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.