ug4
Doxygen Quick Reference

Table of Contents

As written in our Coding Style Guidelines, we are using Doxygen for documentation purposes in ug4.

This is a list and short description of the most frequently used and most important Doxygen commands and tricks. Using these should result in a concise and beatiful documentation.

The full list of available commands can be found in Doxygen's documentation: http://www.stack.nl/~dimitri/doxygen/commands.html

Note
Doxygen is also available for the .lua script files, see Lesson 10 - Doxygen .

General Behaviour of Doxygen

Scope of Paragraph Commands

When ever a paragraph command is used (e.g. note), which does not define a start and end command (as verbatim/endverbatim), the paragraph ends at the next paragraph command or empty line.

Custom Commands for ug4

To ease the "correct" writing of this software we are documenting — ug4 — a custom command (alias) has been defined:

\ug4

which renders to: ug4.

Formatting and Structuring Text

Styling Text

The usual formatting is available.

  • bold
    • for one word: \b word
    • for several words: <strong>several words</strong>
  • italic
    • for one word: \em word
    • for several words: <em>several words</em>
  • typewriter
    • for one word: \c word
    • for several words (inline): <tt>several words</tt>
    • for blocks of code see Special Paragraphs.

Links and References

In case of function and class names, Doxygen is smart and will automatically create a link to the documentation of a function or class whenever it is mentioned inside Doxygen comments.
To force the reference to a class or method one can use the \see command followed by a list of class and method names. Accessing a method of one specific class, the :: and # notation is supported. E.g. MyNamespace::AwesomeClass::print

Full URLs (with http://) and email addresses are converted into links.

To create custom links, either the HTML tag (<a href="place-the-url-here">This is a link</a>) or the reference command (\ref target "Title") can be used. In case "Title" is not given with the \ref command, the name of the section or page is used.

Targets accessible by the \ref command are either defined pages (\page), sections (e.g. \subsection) or arbitrarily defined anchors (\anchor target) somewhere in documents within the include path of Doxygen.

Special Paragraphs

There are some special paragraphs available, which do not only look nice but come sometimes rather handy.

Note
These paragraphs end at the start of the next such paragraph or at an empty line. Indentation ist not required.
Warning
If used within lists or other blocks of HTML, please make sure there is one empty line between the end of such a paragraph and e.g. a closing list item tag ('</li>').
  • \note It might be a good thing to bookmark this page.
    Note
    It might be a good thing to bookmark this page.
  • \remarks Make sure your development toolchain is functional.
    Remarks
    Make sure your development toolchain is functional.
  • \todo Extend the documentation.
    Todo:
    Extend the documentation.

  • \warning Check your pointers!
    Warning
    Check your pointers!

The second type of paragraphs are defined by a starting and closing command. Especially for displaying source code the following are usefull:

  • \code — \endcode to display source code. It offers basic syntax highlighting and automated linking to functions and classes found somewhere else in the documentation.
  • \verbatim — \endverbatim, same as above, but without the fancy syntax highlighting or linking.

Lists

There are two options: One pure and one lazy with a little remark.

  • pure — HTML-Tags There are HTML tags for two kinds of lists:
    • unordered (<ul> - </ul>)
    • ordered (<ol>) - </ol>
    with the items wrapped inside <li> - </li>.

  • lazy — simple Markdown Same possibilities as with HTML, but with simple dashes ('-') followed by a whitespace defining each element. For the ordered list, append a hash ('#') to the dash.

    Note
    The indentation of the text is important!
    - an unordered item of highest level
    - with a unordered item of lover level where the source code
    but not the rendered text spans over several rows
    -# and an order item of highest level
    boost::source
    size_t source(SM_edge< typename T::value_type > const &e, ug::BidirectionalMatrix< T > const &)
    Definition: bidirectional_boost.h:94

    renders to:

    • an unordered item of highest level
      • with a unordered item of lover level where the source code but not the rendered text spans over several rows
    1. and an order item of highest level
    Remarks
    The lazy verariant might not work in full functionality with Doxygen version prior to 1.8.0.

Documenting Classes, Funktions and Variables

To define author and date of creation, the commands \author and \date are available. The first can be used several times.

Parameters, Return Values and Exceptions

  • \brief text
    A very short description of the function showing up in the member list at the top of each class documentation page. It is as well repeated in the detailed documentation of that function, but separated from the detailed description.
    This brief text ends at the line it is defined in, i.e. it can not be longer than one line.
  • \param[in,out] name text
    Documenting the parameter name of the function with a short descriptive text and whether it is only an input (in) or output (out) or both (in,out) paameter.
  • \return text
    Documenting the return value of a function with a descriptive text.
  • \exception type text
    Documenting possible exceptions emitted by a function with their defined type and a descriptive text. Multiple \exception commands are possible.

Grouping Namespaces, Classes and Members

Everything except of pages can be grouped into Modules showing up in a separate group in the documentation. An example of this usage can be found with the lib_algebra, lib_disc and lib_grid modules.

\defgroup identifier name will create such a group, which can be referenced and used by its identifier and show up in the rendered page as name. Make sure this command is only called once per identifier — Doxygen will get confused otherwise and throw errors / warnings.

\addtogroup identifier will add a component to a defined group. You can use @{ and @} to add several components at once: 

/**
 * \addtogroup myPrefiouslyDefinedGroup
 * @{
 * /
class MyClass
{
  void myFunction()
  {
    std::cout << "Hello World!" << std::endl;
  }

  int add(int a, int b)
  {
    return a+b;
  }
}
/** @} * /

For more details about this powerful functionality of Doxygen, see http://www.stack.nl/~dimitri/doxygen/grouping.html

Further Doxygen Tipps

A hierarchy of pages can be achieved with the \subpage command.

Special characters as the dash ('—') should be entered in the form of their HTML entity. (without the whitespaces)

  • '—' -> '& mdash ;'
  • 'ä', 'Ä', 'ß' -> '& auml ;', '& Auml ;', '& szlig ;'
    for the other German umlauts substitute 'a', 'A' respectively.

Horizontal lines are created with the default HTML tag: <hr>.

Building the documentation locally

For a complete build of the documentation (in particular for testing modifications / additions you've made to the documentation before committing) go into ug4/docs directory, then execute in a shell:

doxygen doxy_config_ug4.txt

If you only want to build the documentation (without source code docu), you can do this in the subdir ug4/docs with

doxygen doxy_config_additional.txt

Opening of e.g. the main page of the ug4 documentation in a browser (under OSX, from the shell in the same directory):

open docs/ug4/html/index.html