dune-fem  2.4.1-rc
Some Basic Remarks Concerning Documentation

In the following some remarks on how to add to the Doxygen documentation of dune-fem. Details on doxygen can be found on the Doxygen homepage (see link at bottom of each page). Warnings concerning faullty documentation are recorded in dune-fem/doc/doxygen.out. So this file should be empty...

The following are of course only guidlines - please add to them.

Grouping Documentation

All groups are defined in the fem/modules file using \defgroup; subgrouping is done by adding \ingroup.

The order of these group definitions determines the order in which the groups appear in the "Modules" page of the documentation. Only the major groups which have no obvious class attached to them are documented in the modules file. All others are just declared. Their documentation should be in some obvious header file for example before the namespace Dune is opened or directly following. Preceed the documentation by

\addtogroup Groupname 

If a group combines all implementations for a spesific interface then the documentation for the group should be in the header file containing the interface class and the documentation should refer to this interface class, e.g.,

\remark The interface is defined through the class InterfaceClass

Classes that should appear direcly on the page with the group documentation, e.g., all implementation classes (if they do not belong to a subgroup) should have a \ingroup GroupName in the documentation of the class. It's probably better to have a very short \brief documentation for these classes since this appears on the module page. After the \brief statements, a detailed documentation should follow (after a blank line).

Important classes - either from the user or the implementers point of view

Depricated classes or methods should be tagged with a \deprecated command in the documentation followed by a short remark on the reason for removing this part of the code or alternatives enclosed in quotes.

Documentation of Interface Classes

All methods and typedefs should be documented using \brief. For methods, the arguments and the return type should be documented using

For the typedefs a reference to a corresponding interface class for this type should be included - if one exists. This could be done by, for example, using the \ref command:

\ref MappingInterface "mapping type".

Documentation of Implementation Classes

By using the \copydoc command the documentation from the interface class can be repeated in the implementation class:

/** \copydoc KlassenNameOhneTemplates::funktionOhneParameter */

If the function has been overloaded, the complete function declaration must be given, like this:

/** \copydoc Dune::Fem::LocalFunctionInterface::evaluate(const QuadratureType &quadrature,const int quadPoint,RangeType &ret) const */

Please note that the trailing "const" is important (otherwise Doxygen will look for a non-nonst version of the member).

Note
Doxygen is quite picky about spaces within references. They should be left out whereever possible (see the above example). Moreover, line breaks within references are disallowed.
Type names and Variable names have to be identical to those in the copied documentation.
Template parameters need not be declared as such. But its name has to be identicial to the name declaration whose documentation is copied.

Adding Related Pages

To add a related page, you write a file containing one big C++ doxygen comment. This comment starts with \page, to declare the related page. Then just add the information, the page shall contain. So, the basic structure of the file is as follows:

/** \page MyPageLabel My Page Title
 *
 *  \section My First Section
 *
 *  This is what I have to say ...
 *
 *  \section My Second Section
 *
 *  ... and some more information ...
 */

The file should be placed in "dune-fem/doc/doxygen/pages". Use either ".dev" for development documentation or ".dist" for general documentation as a file extension. Note that developer documentation is not taken over into the distribution.