Skip to content

Doxygen Documentation

Hi,

I was just parsing the output of running Doxygen on our master. One thing I recognised is the following

\section

In the tutorials we make use of Doxygen's \section command. Please be aware that the name given to a section is global. Thus, we get warnings like the following:

Preprocessing .../HyTeG/tutorials/08_CahnHilliard/CahnHilliard.cpp:478: warning: multiple use of section label 'code' while adding section, (first occurrence: .../HyTeG/tutorials/01_PrimitiveStorage.cpp, line 101)

This actually has also a real effect. The corresponding section in tutorial #8 bares the name Complete Program as specified in tutorial #1 and not the name Code as given in tutorial #8.

I suggest to prefix the section names in the tutorials with T<tutorial number>- to make section names unique.

\LaTeX

Do not add pseudo-LaTeX code such as,

/// Evaluates the linear functional
///
///   l( v ) = \int_\Omega f * v
///

but instead put it into a construct to render it as \LaTeX:

/// Evaluates the linear functional
/// \f[
///   l( v ) = \int_\Omega f \cdot v
/// \f]

Also make sure that your \LaTeX commands are supported by standard \LaTeX. Otherwise you will get problems. While additional packages can be loaded by Doxygen via the EXTRA_PACKAGES option, we should IMHO limit this to the really essential stuff for reasons of portability. Currently we only load amsmath in this way.

Note, however, that Doxygen seems not so super stable w.r.t. to treating \LaTeX. For example that following

 * \f{align*}{
 *     F(\phi) = \int \boldsymbol \psi(\phi) dx + \frac{\epsilon^2}{2}\int |\nabla \phi |^2 dx
 * \f}

seems to be responsible for

warning: Found unknown command '\boldsymbol'
warning: Found unknown command '\psi'

although it is type-set correctly in the output and (at least to me) seems to adhere to the specification.

Other Issues

Most other warnings seem to belong to one of four categories:

  • The following parameter of XYZ is not documented:, which would be easy to fix by adding the respective documentations. Unless XYZ is a templated function. I see cases where there is an attempt to document the parameter, but Doxygen seems to have problems to understand this for a concrete template instantiation. Not sure if one can help Doxygen here.
  • warning: no uniquely matching class member found for XYZ which, without looking too much into details seems to be related to templatisation and, thus, might be unfixable.
  • warning: explicit link request to 'XYZ' could not be resolved, where XYZ is something like P1Function or ValueType, so again related to templatisation.
  • warning: member XYZ belongs to two different groups. The second one found here will be ignored. Not sure about that one, yet.

Pictures

This is more of a question. Can someone please explain to me, why we need to explicitely add pictures, used e.g. in the tutorials, to EXTRA_HTML_FILES when we include them using <img src="..."/>? This only seems to bother Doxygen, when we build the documentation as part of the pipeline, but not, when one builds it locally. What's the difference and could that maybe be resolved?

Edited by Marcus Mohr