Documentation comments vs other types of code commenting

Comments serve two purposes:

Documentation. Documentation comments are comments formatted and positioned in a way to be interpreted by a documentation generator (WARPXM currently uses Doxygen). As they will form part of stand-alone documentation, all comments in documentation blocks must be understandable and meaningful without direct access to the code.
Clarification. Clarification comments are not captured by the documentation generator, but are intended to be read with code. As the name indicates, clarification comments serve to clarify coding choices and explain sections of code whose purpose may not be immediately obvious.

Documentation generation tool: Doxygen

Per the Doxygen website:

‍Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, and to some extent D. Doxygen also supports the hardware description language VHDL.

Doxygen can help you in three ways:

It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in $\mbox{\LaTeX}$) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

You can also use doxygen for creating normal documentation (as I did for the doxygen user manual and web-site).

Doxygen install instructions

Latest version downloads and install instructions can be found here.

WARNING: As of July 2023, version 1.9.7 has a bug that prevents linking of markdown files in the page index layout. Use Doxygen version 1.9.6 until further notice.

Building documentation locally

After running cmake on the build directory (see WARPXM install instructions), build the documentation

whitneythomas@euler:~/code/warpxm/build% make doc

Updating web documentation

Web documentation can only be updated by authorized users and can only be done while on the master branch. The most up-to-date instructions for getting authorization and updating web documentation can be found in tools/update_webdocs.sh.

C++

Thorough documentation comments in all C++ declarations (found in header files) is strongly encouraged. This section details where and how to document declarations so that they can be interpreted successfully by Doxygen. See this this MHD floor app as an example.

What to document

Declarations (found in header files) should be documented. This includes

classes
complex class member functions
class attributes
complex functions
structs

Minimum documentation should include a brief (one line) description and any particular usage instructions not obvious from the name itself. Use your best judgment.

For more complex, or physics based classes, the documentation comment is a good place to include references, equations, assumptions, and limitations of applicability.

Indicating documentation comments

Doxygen-readable comments are indicated by special markings. Doxygen supports the use of several alternative formats. In WARPXM, the chosen formatting is as follows for comment blocks

/**
* ...Comment block text goes here...
*/

and inline comments (used strictly after members of a file, class, struct, enum, etc.)

int x; /**< Inline comment text goes here. */

Doxygen commands

Doxygen also recognizes a number of keywords or commands. Commands are indicated by a preceding "\\" or "" (for WARPXM documentation comments, "@" is preferred). Commonly used commands are described below. For a complete list of available commands see the Doxygen website.

**@brief** (@brief {description}). Starts a paragraph that serves as a brief description. For classes and files the brief description will be used in lists and at the start of the documentation page. For class and file members, the brief description will be placed at the declaration of the member and prepended to the detailed description. A brief description ends when a blank line or another sectioning command is encountered.
```
\**
 * @brief A brief description of the class or function.
 */
```
**@exception** (@exception <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.
**@param** (@param [(dir)] <parameter-name> {parameter description}). Starts a parameter description for a function parameter with name <parameter-name>, followed by a description of the parameter. The existence of the parameter is checked and a warning is given if the documentation of this (or any other) parameter is missing or not present in the function declaration or definition.

The @param command has an optional attribute, (dir), specifying the direction of the parameter. Possible values are: "[in]", "[in,out]", and "[out]".
```
/**
 * Copies bytes from a source memory area to a destination memory area,
 * where both areas may not overlap.
 * @param[out] dest The memory area to copy to.
 * @param[in]  src  The memory area to copy from.
 * @param[in]  n    The number of bytes to copy
 */
void memcpy(void *dest, const void *src, size_t n);
```
Note that you can also document multiple parameters with a single @param command using a comma separated list. Here is an example:
```
/** Sets the position.
 *  @param x,y,z Coordinates of the position in 3D space.
 */
void setPosition(double x,double y,double z,double t)
```
**@return** (@return { description of the return value }). Starts a return value description for a function.
**@see** or **@sa** (@see { references } or @see { reference }). 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.
**@todo** (@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. Each item in the TODO list will be preceded by a header that indicates the origin of the item.

Documenting classes, structs, enums and methods

Documentation comments for classes, structs, enums, and methods are placed in comment blocks in the header file and precede the class or member method declaration. Inline comments are used for attributes only.

/**
 *  @brief A test class.
 *
 *  A more elaborate class description.
 */
class ClassName
{
public:
    /**
     * @brief A constructor.
     *
     * A more elaborate description of the constructor.
     */
    ClassName();

    /**
     * @brief A destructor.
     */
    ~ClassName();

    /**
     * @brief A normal member taking two arguments and returning an integer value.
     * @param a An integer argument.
     * @param s A constant character pointer.
     * @see ClassName()
     * @see ~ClassName()
     * @return The test results
     */
    int testMe(int a,const char *s);

    /**
     * @brief A pure virtual member.
     * @see testMe()
     * @param c1 The first argument.
     * @param c2 the second argument.
     * @todo Make it do something useful.
     */
    virtual void testMeToo(char c1,char c2) = 0;

private:
    int x; /**< A private integer. */
    double y; /**< A private double. */
};

Text formatting

Doxygen supports markdown syntax for text formatting of paragraphs, headings, lists, emphasis, and links. See documentation.

Math formatting

Doxygen supports a number of common LaTeXcommands, including inline and block equations.

Inline LaTeXcommands, not math mode. Bracket LaTeXcommand with \f( and \f).
```
Inline \f(\Latex\f) commands are indicated thusly.
```

Inline equations. Bracket inline equations with \f$ and \f$.

Inline equations are done thusly: \f$ \sqrt{x^2 + y^2} = z\f$.

Ordinary math blocks. Standard LaTeXmath blocks are indicated by \f[ and \f].

\f[
    \frac{\partial \tilde{\rho}_p}{\partial t} +
    \tilde{\nabla} \cdot \left(\tilde{\boldsymbol{p}_p} \right) =
    A_p \left(\tilde{\Gamma}^{ion}_i - \tilde{\Gamma}^{rec}_n \right)
\f]

Fancy math blocks. Fancy math blocks that use environments like align or eqnarray can be indicated with braces.

\f{align*}{
    \rho_{out} &= \max (\rho_{min}, \rho_{in}) \\
    \boldsymbol{p}_{out} &= \boldsymbol{p}_{in}, \\
    e_{out} &= \frac{1}{\gamma-1} \max (P_{min}, P_{in}) + \frac{1}{2} \max \left(
    \rho_{min}, \rho_{in} \right)^{-1} \left(p_x^2 + p_y^2 + p_z^2 \right)_{in}.
\f}

A word of caution from the Doxygen manual

‍Currently, Doxygen is not very fault tolerant in recovering from typos in formulas. It may be necessary to remove the files formula.repository that are written to the html, rtf etc. directories to get rid of an incorrect formula as well as the form_* files.

For more information, see the Doxygen documentation.

Python

Guidelines for Python documentation commenting are minimal. The priority of Doxygen documentation commenting is lower for Python than C++ code for two reasons:

WARPXM is primarily at C++ code. Python is used exclusively for pre- and post-processing libraries.
Doxygen support for Python is not as comprehensive as its support for C++.

Doxygen readable comment blocks for Python will share the same format as for C++ (see previous section), except that they will be in docstrings (contained in triple quotes after the class of function declaration). In order for Doxygen to recognize special commands, the opening triple quote should be followed by a bang, ex. ‘’''!`. See this discussion for more details.

'''! @package warpy
@brief A collection of pre- and post-processing tools for warpxm.

A longer description with more information. Blah. Blah. Blah.
'''

Anywhere documentation in Python code duplicates documentation in C++ code (ex. warpy app classes), then the Python documentation code should be minimal, and contain at most a brief description and link to the C++ class or file.

class euler(application):
    '''
    @brief Euler, or 5-moment, fluid advection application.

    @sa wxm::apps::five_moment::euler_t
    '''
    def __init__(self, name, ...):

Where more extensive documenting of Python code is necessary, the formatting is similar to C++. Note that arguments are defined in the __init__ method

class application(warpy_obj):
    '''!
    @brief A brief description.

    A longer description can go here.
    @extends warpy_obj
    '''

    def __init__(self, name, req_attrs, opt_attrs=None):
        '''!
        @brief Initializes important object variables.
        @param name The name of the application.
        @param req_attrs A dictionary of attribute name-value pairs.
        @param opt_attrs Same as req_attrs but are optional.
        '''

Clarification comments

Clarification comments in all code are encouraged, but no formal formatting is specified. Comments should explain reasoning and methodology not immediately clear from the code itself.

Inline comments are discouraged, except in special cases,

Closing brackets on C++ namespaces. Namespaces can be nested several deep. Commenting the closing bracket of a namespace helps keep track of where a namespace is valid and assists with housekeeping.
```
namespace wxm
{
namespace apps
{
namespace functions
{
namespace five_moment
{

... Bunch of code...

} // namespace five_moment
} // namespace functions
} // namespace apps
} // namespace wxm
```
Variable initializations that need extra clarification.

Use your best judgment!

Table of Contents