Doxygen - PIK-LPJmL/LPJmL GitHub Wiki

Doxygen

is a tool, to generate a documentation from source code and create nice call and caller graphs

see http://www.stack.nl/~dimitri/doxygen/

Documentation of the code

Comments

Comments which are helpful, but not important for doxygen, like:

} /* end of function ... */

should contain only one asterisk in the comment (/* , */).

Those parts of the code, which are important for doxygen should be commented according to the guidelines for C (++) in the manual: Doxygen Manual
Using a block of double asterisks at top and bottom and one asterisk at the beginning of every line (/**** ****/):

/**
* .. annotation ..
**/

or

/** .. annotation ..*/

is a good option for basic comments! Most important are these comments directly above important code structures like classes or function definitions:

Special Comments

/**
*    \brief A test function.
*    \param[in] inputvar description
*    \param[out] outputvar description
*
*    A more detailed class description.
**/

Here the special command [in]/[out] describes the type of variable (input/output), it can be left out.
Parameters can also be commented inline, like this:

int function test( 
                       int inParameter1, /**< inParameter1 description of it. */
                       char* inParameter2  /**<  inParameter2 description of it. */ 
                       ); /** \return returnVariable description */

Or just for simple variable declarations:

int var; /**< Detailed description after the member */

Where do i get it?

Ubuntu/Debian [other linux-based OSs]

for linux it is in the standard sources:

sudo apt-get install doxygen

also you need graphviz:

sudo apt-get install graphviz

Windows

For Windows you need to download and install doxygen (doxygen-X.X.XX-setup.exe) Download doxygen and graphviz (graphviz-X.XX.msi) Downloadlink graphviz.
Then edit the PATH variable, to include the directories for the executables of both.

First create default configfile Doxyfile in main folder of LPJmL (so that src/ and include/ can be directly reached):

doxygen -g

modify Doxyfile:

  • set EXTRACT_ALL, RECURSIVE (then you don’t have to specify all subdirs), HAVE_DOT, CALL_GRAPH and CALLER_GRAPH to “YES”

  • FILE_PATTERNS to mainly used filetype “.c.h” (without colon and quotation marks -- this prevents doxygen to also create a doc for other files, like Makefiles)

  • INPUT is not necessary, since it resides in the main folder and all files can be reached recursively from there

optional:

  • SOURCE_BROWSER = YES, if you want source code links

  • GENERATE_LATEX = NO, if you don’t want to use a latex doc as well

  • OUTPUT_DIRECTORY can be set to arbitrary name e.g. “doxygen”, then in this folder an html/ folder (can also be renamed with HTML_OUTPUT) contains the documentation

  • MACRO_EXPANSION and EXPAND_ONLY_PREDEF might be considered if detailed description of macros is desired

run with:

doxygen Doxyfile

view documentation:

look for index.html in the newly created html/ folder (inside the OUTPUT folder, if set)

description of call/caller graphs

  • A white box indicates a class or struct or file.

  • A box with a red border indicates a node that has more arrows than are shown! In other words: the graph is truncated with respect to this node. The reason why a graph is sometimes truncated is to prevent images from becoming too large. For the graphs generated with dot doxygen tries to limit the width of the resulting image to 1024 pixels.

  • A black box indicates that the class’ documentation is currently shown.

  • A dark blue arrow indicates an include relation (for the include dependency graph) or public inheritance (for the other graphs).

  • A dark green arrow indicates protected inheritance.

  • A dark red arrow indicates private inheritance.

  • A purple dashed arrow indicated a “usage” relation, the edge of the arrow is labeled with the variable(s) responsible for the relation. Class A uses class B, if class A has a member variable m of type C, where B is a subtype of C (e.g. C could be B, B**, T**).

flaws, at the moment:

  • doxygen needs a special annotation system to read comments from the code - so we can (at the moment) only use it for the graphs
  • doxygen is not without help able to document pointer changes on variables (function(var) would be needed) and thus misses some important parts of the code