Documenting with Doxygen for Dummies

Installing and Turning On Doxygen Documentation

To download Doxygen using Ubuntu, simply open a terminal (ctrl + alt + t) type:

sudo apt-get install doxygen

Once Doxygen is successfully installed, Mercury documentation can then be turned on by typing

ccmake .

in the "build" directory and turning "MercuryDPM_BUILD_DOCUMENTATION" on, before configuring and generating as normal (for further details, see the MercuryDPM installation guide).

Using Doxygen

Making a New Page with Doxygen:

To make a new page (such as this), you need to create a ".dox" file.

The safest way to do this in Mercury is to copy an existing file using the following command:

svn cp oldFile.dox newFile.dox

This creates a new file which is simply a copy of the old. By adding "svn", we ensure that the new file is added to the repository.

The new file can then be edited at will.

All Doxygen files should be started with a line that reads:

/*! </TT>page [KEYWORD] [TITLE]

and ended with:

*/

Here, the "keyword" allows the page created to be linked to from other pages using the ref command followed by the keyword.

html documentation can then can then be created by simply typing

make doc

in your build directory.

Documenting Code with Doxygen:

In any of MercuryDPM's .h or .cc files, comments can be added to the code that will also appear in the Doxygen documentation by starting the comments with:

/*!

and ending with

*/

as above.

Comments written within these symbols will not only be visible in the code itself, but will also be added to the MercuryDPM documentation.

Documentation Style

  1. Put brief comments (\brief) in the header (.h) files.
  2. Put full comments (\details) in the CC (.cc) files, including documentation of the in- and out-put parameters (\param[in], \param[in]).
  3. If a function is deprecated add the tag \deprecated and PROVIDE A REFERENCE TO A SUITABLE REPLACEMENT FUNCTION.
  4. If a function contains a bug, detail the bug using the tag \bug (or, better still, fix it!).
  5. Do this for every class and every member variable.

The full MercuryDPM documentation can be viewed offline by going to /Documentation/html in the "build" directory and typing

[YOUR_WEB_BROWSER] index.html