Documentation

Doxygen Guidelines

This document explains the formatting and style for documenting code. To build the documentation, see Building Documentation for information on documenting and building documentation.

Overview

• Methods and xml format to use in methods
• Algorithms should be documented inline with source rather than headers
• Interface details should remain with headers

Table of contents

• Using TODO
• Documenting the heads of each file
• Documenting member fields
• Snippets and Code Samples
• Adding images for headers/sources, and markdown files (.md)

Using TODO

To have a TODO automatically pull to documentation use:
/// TODO:

Documenting the heads of each file (headers and sources)

The head of each file should contain the following tags:

\file
Name of a file
e.g. /// \file node.h
https://www.doxygen.nl/manual/commands.html#cmdfile

\brief
A one-line description describing the contents of the file
e.g. /// \brief Header file for a node data structure, used in a graph ADT
https://www.doxygen.nl/manual/commands.html#cmdbrief

\author
The author of the file
If there are multiple authors,
you may use one \author tag for all of the authors,
or one \author tag per person/entity.
e.g. /// \author John Doe
https://www.doxygen.nl/manual/commands.html#cmdauthor

\date
This may be the date of the file's last update,
or the date the file was created – whichever is relevant.
e.g. /// \date 06 Jun 2020
https://www.doxygen.nl/manual/commands.html#cmddate

An example of a file head would look like this:

///
/// \file       node.h
/// \brief      Header file for a node data structure, used in a graph ADT
///
/// \author     John Doe
/// \date       06 Jun 2020
///

Other notes:

• Follow each /// with a single space, before using a tag.
• Follow each tag with two tabs, then provide the description.

Documenting member fields

Here is a simple example:
struct position { float x, y, z; ///< Cartesian coordinates x, y, and z int id; ///< Unique identifier };

The general format is ///< Description goes here,
notice that a single whitespace character follows ///<
and the field descriptions are in alignment with each other, using tabs.
Sometimes, this is not always possible,
but do your best to keep the formatting neat and consistent.

Snippets and code samples

The \snippet tag should be used for long examples that are over 10 lines.

https://www.doxygen.nl/manual/commands.html#cmdsnippet

Step 0:
In a header file, at the line where you want the snippet to appear:

/// \snippet PATH_TO_FILE\filename.cpp SnippetName

If you would like to include line numbers for the snippet, you may use the tag \snippet{lineno} This is best used for directly referencing source files from within this repo, since the line numbers that appear are the actual line numbers of the code used for the snippet.

Step 1:
In PATH_TO_FILE\filename.cpp (where the snippet sample is),

/// [SnippetName]
std::cout << "My sample snippet" << std::endl;
/// [SnippetName]

Notice that the code is not a comment.