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.

Documenting Code

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.

File documentation

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.

Class documentation

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:

Member Data

@brief

Methods (including stand-alone non-member functions)

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

Program documentation

@brief
Detailed description including usage information

Other code constructs

@brief

Miscellaneous commands

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.

Formats for Code Comments

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.

Headers

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 first level header

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

This is a second level header

  ###Third level header

Third level header

Italics and Bold

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>).

Lists

A bulleted list can be created like this:

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

Element 1
Element 2
1. Subelement 1
2. 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

Links

Embed links in your documentation like this:

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

XPACC Jira

Blockquotes and Code Sections

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

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

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$

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

Tips for converting Latex to Doxygen

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.

Enabling latex style commands in Doxygen

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 $\ensuremath{\mathit{Re}}$ .

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.

Converting formulas

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.