Doxygen Quick Guide

This page provides a quick guide to using doxygen for documenting your software. It briefly discusses the most important concepts and commands. For details, please refer to the Doxygen User Manual.

Contents:

• Documenting the Code
  • Refering to Documents on the LOFAR Document Server
• Grouping
  • Modules
  • Member Groups
• Using Formulas
• Useful Commands
  • Structural Indicators
  • Section Indicators
  • Commands for Visual Enhancements

---

Documenting the Code

All the comments in the *.h header files of the LOFAR source tree will be documented. You don't need to use special comment delimiters to identify documentation blocks; you can use the ordinary C++ style // comment delimiter.

All documentation blocks are treated as detailed descriptions (see the Doxygen User Manual for an explanation of brief and detailed descriptions). A blank line ends a documentation block.

Comments that should not be documented should be identified using the "special" //# comment delimiter.

For more information, please refer to the LOFAR C++ Coding Standard.

Refering to Documents on the LOFAR Document Server

There will be times when you want to point a reader to one or more documents on the LOFAR Document Server (http://www.lofar.org/project/lofardoc/document.php). In order to do so, you need to know a little bit of the way that this site is structured.

The document server is powered by PHP. A document is searched in the database, using a PHP query command. The general form of this command is:

    ?action=match&docname=<docname>
  

Documents names are composed as follows:

    LOFAR-<origin>-<document-type>-<document number>
  

So, for example, when you want to direct a reader to the document LOFAR Build Environment, which has the name LOFAR-ASTRON-MEM-006, you should add the following URL in the documentation:
<a href="http://www.lofar.org/project/lofardoc/document.php?action=match&docname=LOFAR-ASTRON-MEM-006">LOFAR Build Environment</a>.

[Back to Contents]

---

Grouping

Doxygen has two mechanisms to group things together. One mechanism works at a global level, creating a new page for each group. These groups are called modules in the documentation. The other mechanism works within a member list of some compound entity, and is refered to as a member group.

Modules

Modules are a way to group things together on a separate page. Groups can be nested, so you can create a complete hierarchy of groups and subgroups. You can best think of a group as a set of logically related entities; for example, a collection of classes that together form a logical unit (e.g. a design pattern). If you use grouping in this way, you can clarify the high-level design of your software.

To define a group you should use the \defgroup command. You can make an entity a member of a specific group using the \ingroup command. To avoid putting a \ingroup command in the documentation of each member, you can also group members together using the open and close group markers @{ and @}.

You can use \addtogroup instead of \defgroup; in that case Doxygen will not enforce unique labels.

Example:

// \defgroup mathematics Mathematics

// \ingroup mathematics
// \defgroup math_constants Math Constants
// @{

// Ratio of a circle's circumference to its diameter, \f$\pi\f$.
const Real pi = M_PI; // 3.14159265358979323846264338327950288;

// @}


// \ingroup mathematics
// \defgroup elementary_math Elementary Math
// @{

// Return the square of the argument \a x.
template<typename T>
inline T sqr(T x)
{
  return x*x;
}

// @}

This is the corresponding HTML documentation generated by Doxygen.

Note:

Grouping is a very powerful mechanism. However, its complexity can be a bit intimidating at first. You should play around a bit with modules to get a good grisp. You will see that this is time well spent!

Member Groups

If a compound (e.g. a class or file) has many members, it is often desired to group them together. Doxygen already automatically groups things together on type and protection level, but maybe you feel that this is not enough or that that default grouping is wrong.

A member group is defined by the pair of open and close group markers @{ and @} and anything that goes in between. Nesting of member groups is not allowed.

Example:

// Define shorthands for various data types.
// The types are in a namespace to prevent pollution of the global namespace.
namespace TYPES
{
  // \name Vectors
  //@{
  typedef blitz::Array<Integer,1>  VectorInteger;
  typedef blitz::Array<Real,1>     VectorReal;
  typedef blitz::Array<Double,1>   VectorDouble;
  typedef blitz::Array<Complex,1>  VectorComplex;
  typedef blitz::Array<DComplex,1> VectorDComplex;
  //@}
}

This is the corresponding HTML documentation generated by Doxygen.

[Back to Contents]

---

Using Formulas

Doxygen allows you to put formulas in the output (this works only for the HTML and output, not for the RTF nor for the man page output).

There are two ways to include formulas in the documentation.

1. Using in-text formulas that appear in the running text. These formulas should be put between a pair of \f$ commands.
2. Unnumbered displayed formulas that are centered on a separate line. These formulas should be put between \f[ and \f] commands.

Formulas should be valid commands in 's math-mode. For details, please refer to the Doxygen User Manual.

Example:

  In order to solve the equation \f$ax^2 + bx + c = 0\f$, we can use the
  following well-known formula:
  \f[
    x = -b \pm \frac{\sqrt{b^2 - 4ac}}{2a}
  \f]
  

will result in the following text:
In order to solve the equation , we can use the following well-known formula:

[Back to Contents]

---

Useful Commands

This section provides an overview of the most useful Doxygen commands to be used when documenting LOFAR software. It contains the following subsections:

• Structural Indicators
• Section Indicators
• Commands for Visual Enhancements

Structural Indicators

\\addtogroup <name> [(title)]

Defines a group just like \defgroup, but in contrast to that command using the same <name> more than once will not result in a warning, but rather one group with a merged documentation and the first title found in any of the commands.

The title is optional, so this command can also be used to add a number of entities to an existing group using @{ and @} like this:

  // \addtogroup mygrp
  // Additional documentation for group `mygrp'
  // @{

  // A function 
  void func1();

  // Another function
  void func2();

  // @}

\\defgroup <name> (group title)

Indicates that a comment block contains documentation for a group of classes, files or namespaces. This can be used to categorize classes, files or namespaces, and document those categories. You can also use groups as members of other groups, thus building a hierarchy of groups.

The <name> argument should be a single-word identifier.

\\ingroup (<groupname> [<groupname> <groupname>])

If the \ingroup command is placed in a comment block of a class, file or namespace, then it will be added to the group or groups identified by <groupname>.

\\name (header)

This command turns a comment block into a header definition of a member group. The comment block should be followed by a // @{ ... // @} block containing the members of the group.

[Back to Contents]

---

Section Indicators

\\note { text }

Starts a paragraph where a note can be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph.

\\par [(paragraph title)] { paragraph }

If a paragraph title is given this command starts a paragraph with a user defined heading. The heading extends until the end of the line. The paragraph following the command will be indented. If no paragraph title is given this command will start a new paragraph.

The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph.

\\post { description of the postcondition }

Starts a paragraph where the postcondition of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph.

\\pre { description of the precondition }

Starts a paragraph where the precondition of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph.

\\return { description of the return value }

Starts a return value description for a function. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph.

\\sa { references }

Starts a paragraph where one or more cross-references to classes, functions, methods, variables, files or URL may be specified. Two names joined by either :: or # are understood as referring to a class and one of its members. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method name.

Synonymous to \see.

\\throw <exception-object> { exception description }

Starts an exception description for an exception object with name <exception-object>. Followed by a description of the exception. The existence of the exception object is not checked. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. The \throw description ends when a blank line or some other sectioning command is encountered.

Synonymous to \exception.

\\todo { paragraph describing what is to be done }

Starts a paragraph where a TODO item is described. The description will also add an item to a separate TODO list. The two instances of the description will be cross-referenced.

\\warning { warning message }

Starts a paragraph where one or more warning messages may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. The \warning command ends when a blank line or some other sectioning command is encountered.

[Back to Contents]

---

Commands for Visual Enhancements

\\a <word>

Displays the argument <word> using a special font. Use this command to refer to member arguments in the running text.

Example:

  ... the \a x and \a y coordinates are used to ...
  

This will result in the following text:

... the x and y coordinates are used to ...

\\b <word>

Displays the argument <word> using a bold font.

To put multiple words in bold use <b>multiple words</b>.

\\c <word>

Displays the argument <word> using a typewriter font. Use this to refer to a word of code.

Example:

Typing:

     ... This function returns \c void and not \c int ...
  

will result in the following text:

... This function returns void and not int ...

To put multiple words in typewriter font use <tt>multiple words</tt>.

\\code

Starts a block of code. A code block is treated differently from ordinary text. It is interpreted as C/C++ code. The names of the classes and members that are documented are automatically replaced by links to the documentation.

See also:

\endcode, and \verbatim

\\e <word>

Displays the argument <word> in italics. Use this command to emphasize words.

Example:

Typing:

  ... this is a \e really good example ... 
  

will result in the following text:

... this is a really good example ...

Equivalent to \em. To emphasize multiple words use <em>multiple words</em>.

\\endcode

Ends a block of code.

See also:

section \code

\\verbatim

Starts a block of text that will be verbatim included in both the HTML and the documentation. The block should end with a \endverbatim command. All commands are disabled in a verbatim block.

[Back to Contents]

---