Doxygen Documentation Guide

This is a sort of quickstart guide to using Doxygen in XPACC codes.

Default doxygen documentation is not very good. It really needs to be configured and guided by doxygen markup. The markup can go in the code (as is usual), or it can go into *.dox files anywhere in the source tree. Dox files help avoid cluttering the code with doxygen markup, but use of them carries increased risk of undocumented (or worse: *wrong* documented) code as it evolves. Any improvements or suggestions on better practices are welcome.

General notes & guidelines:

- Doxygen is used to generate source code documentation
- Doxygen comments should be in the source files, or *.dox files. (keeps headers clear)
- Use mostly regular comments in headers (if any)
- Use @command style, and
**not**\command style Doxygen commands. This is consistent with XPACC-developed annotations.

Required Doxygen tags

- @file
- @brief
- @author

- Note
- The @file tag is unnecessary when the documentation appears near the top of a file and is clearly not associated with any other code construct.

All classes should have a brief and detailed description that at least indicates what the class does. If the class has public or protected members, then those should be documented as follows:

- @brief

For functions, please include the parameter descriptions **before** the further details about usage, limitations, etc. In general, the more than can be said about a function, the better.

- @brief
- @param
- @returns
- Detailed description

- @brief
- Detailed description including usage information

- @brief

A few other Doxygen commands are useful when documenting code and projects. The *issues* created with these commands are automatically collated into a summary pages dedicated to the issue type (i.e. bug, note, warning, or todo). This provides a convenient summary of all (known) bugs or a TODO list for a code or project.

- @bug - allows a description of bugs in code constructs or programs
- @note - is a general noting facility allowing construct-associated notes
- @warning - is useful for alerting users or developers about construct-associated pitfalls or limitations
- @todo - provides developers a way to note things left to do for a project or implementation

Examples of the documentation generated by the above commands:

- Note
- These commands are useful for creating notes on projects or constructs which are automatically summarized inline as well as in dedicated documentation pages.

**Bug:**- No known bugs.

- Warning
- Coding is inherently dangerous.

**Todo:**- Refactor away redundant code.

Doxygen interprets special commands and formatting in comments to generate documentation for your code and project. Doxygen also supports the *Markdown* markup language for formatting its generated documentation. The following sections are meant to be a summary with examples for some of the most useful commands and formats.

All of the documentation below is generated by the file: `doc/Documentation.dox`

Open it in your favorite editor to see how the documentation constructs below are created from comment formatting.

Markdown formats, and some html tags can be used inline with your comments to make your documentation pretty and more readable. Some useful examples follow.

The following examples show the syntax in a block quote, followed directly by how it would look in the generated documentation.

Different kinds of headers can be created like these...

This is a first level header ===========================

This is a second level header ---------------------------

###Third level header

You can create *italics* by encasing in underscores like this (_italics_) and **bold** by encasing in asterics like this (**bold**) or by using html tags like this (<b>bold</b>).

A bulleted list can be created like this:

- Element 1 - Element 2 -# Subelement 1 -# Subelement 2 - Element 3

- Element 1
- Element 2
- Subelement 1
- Subelement 2

- Element 3

Lists of numbered items are created like this...

1. Element 1 2. Element 2 3. Element 3

- Element 1
- Element 2
- Element 3

Embed links in your documentation like this:

[XPACC Jira](https://xpaccillinois.atlassian.net "This is the mouseover text.")

Blockquotes can be made by using the >, like this:

> Use blockquotes especially when documenting user > commands and stuff like that. > New lines are ignored internally but can be done\n > by forcing with "\n"

Use blockquotes especially when documenting user commands and stuff like that. New lines are ignored internally but can be done

by forcing with "\n"

Blockquotes can also be created with the <blockquote> html tag:

<blockquote> This text will be block-quoted.\n The blockquote continues on the next line. </blockquote>

This text will be block-quoted.

The blockquote continues on the next line.

Note the explicit forcing of a newline with "\n".

Code snippets can also be encapsulated as such: @code int test_code_section; char disco_inferno; @endcode

int test_code_section;

char disco_inferno;

Tables are simple to create in doxygen with the Markdown syntax. Here's the syntax for the following example table:

| Type | Description | Usage | Value | | ----: | :----------------: | :------------: | :-------------- | | 0 | simple flag | -t | .true. | | 1 | argument optional | -t or -t [arg] | .true. or [arg] | | 2 | argument required | -t <arg> | <arg> | | 3 | required w/arg | -t <arg> | <arg> |

creates the following table:

Type | Description | Usage | Value |
---|---|---|---|

0 | simple flag | -t | .true. |

1 | argument optional | -t or -t [arg] | .true. or [arg] |

2 | argument required | -t <arg> | <arg> |

3 | required w/arg | -t <arg> | <arg> |

Latex can be directly embedded into your comments by delineating the latex code in \f$'s.

\f$\bar{\mu} = \frac{1}{N}\Sigma_{n=1}{N}\frac{x_n}{n!}\f$

It is relatively straight-forward to convert existing latex documentation into a format that can be generated with latex. Below are a couple of tips for making the process as painless as possible.

It is common to find custom-defined commands in *Latex* documents and it is possible to port those commands over to *Doxygen* in order to retain some of this portability. *Doxygen* uses `ALIASES`

to provide this function. For example, the line

ALIASES = "eg=@e.g." \

"RE=\f$\ensuremath{\mathit{Re}}"

provides the custom commands ` \eg `

and ` \RE `

in the doxygen documentation as *e.g*. and .

This approach does not add the new commands to the doxygen latex formula interpreter. This can be achieved however by placing the commands in a seperate style file and specifying that file with the *Doxygen* option `LATEX_EXTRA_STYLESHEET`

. For example, placing the following lines in a file names PlasComCM.sty

\newcommand{\RE}{\ensuremath{\mathit{Re}}}

\newcommand{\eg}{\emph{e.g.}}

Provides the same commands as above in latex math-mode.

*Doxygen* has the capability to interpret latex formulas, but adding the surrounding syntax can be time consuming if there are a lot of equations inline. In *vim*, typing the following will correctly format every latex equation on a single line

:s[\$[\\f\$[g

It is also worth noting that multi-line constructions such as \begin{equation} can be replaced with a `\f[...]\f`

syntax like so

\f[\begin{aligned}

t &= t^* /(L^* / c^*_\infty) \\

x_i &= x_i^* /L^* \\

\rho &= \rho^* /\rho^*_\infty \\

u_i &= u^*_i/c^*_\infty \\

p &= p^* /(\rho^*_\infty c^{*2}_\infty) \\

\mu &= \mu^* /\mu^*_\infty \\

\lambda &= \lambda^* /\mu^*_\infty \\

T &= T^* /(c^{*2}_\infty/C^*_{p,\infty}) = T^* / [(\gamma_\infty-1)T^*_\infty]

\end{aligned}

\f]

becomes

\f[\begin{aligned}

t &= t^* /(L^* / c^*_\infty) \\

x_i &= x_i^* /L^* \\

\rho &= \rho^* /\rho^*_\infty \\

u_i &= u^*_i/c^*_\infty \\

p &= p^* /(\rho^*_\infty c^{*2}_\infty) \\

\mu &= \mu^* /\mu^*_\infty \\

\lambda &= \lambda^* /\mu^*_\infty \\

T &= T^* /(c^{*2}_\infty/C^*_{p,\infty}) = T^* / [(\gamma_\infty-1)T^*_\infty]

\end{aligned}

\f]

When a latex construct is used that automatically begins a math enviroment we instead use a \f{command}{...\f} construct as illustrated by the following syntax.

\begin{multline}

\frac{\partial\rho E}{\partial t} = \cdots \frac{1}{\RE\PR}\frac{\partial \mu}{\partial x_i}\frac{\partial T}{\partial x_i} + \frac{\mu}{\RE\PR}\frac{\partial^2 T}{\partial x_i x_i} \\

{} + \left\{\frac{1}{\RE}\frac{\partial \mu}{\partial x_j}\left(\frac{\partial u_i}{\partial x_j}+\frac{\partial u_j}{\partial x_i}\right) + \frac{1}{\RE}\frac{\partial \lambda}{\partial x_i}\frac{\partial u_k}{\partial x_k} + \frac{\mu}{\RE}\left(\frac{\partial^2u_i}{\partial x_j\partial x_j} + \frac{\partial^2u_j}{\partial x_i\partial x_j}\right) + \frac{\lambda}{\RE}\frac{\partial^2 u_k}{\partial x_i \partial x_k}\right\}\frac{\partial u_i}{\partial x_j}

\end{multline}

becomes

\f{multline}{\nonumber

\frac{\partial\rho E}{\partial t} = \cdots \frac{1}{\RE\PR}\frac{\partial \mu}{\partial x_i}\frac{\partial T}{\partial x_i} + \frac{\mu}{\RE\PR}\frac{\partial^2 T}{\partial x_i x_i} \\

{} + \left\{\frac{1}{\RE}\frac{\partial \mu}{\partial x_j}\left(\frac{\partial u_i}{\partial x_j}+\frac{\partial u_j}{\partial x_i}\right) + \frac{1}{\RE}\frac{\partial \lambda}{\partial x_i}\frac{\partial u_k}{\partial x_k} + \frac{\mu}{\RE}\left(\frac{\partial^2u_i}{\partial x_j\partial x_j} + \frac{\partial^2u_j}{\partial x_i\partial x_j}\right) + \frac{\lambda}{\RE}\frac{\partial^2 u_k}{\partial x_i \partial x_k}\right\}\frac{\partial u_i}{\partial x_j}

\f}

The only drawback to doing equations in this manner is a loss of referencing to individual equations, which is apparently not supported by *Doxygen*.