Documenting Code with Doxygen

In order to help with documenting our source code, we have set up Doxygen for the project. When anything gets pushed or merged to master, the CI will automatically generate documentation and will publish it at https://huskyroboticsteam.github.io/Resurgence. You shouldn't need to actually install anything on your computer unless you want to generate a local copy of the documentation. Note: please do not check any generated documentation into Git! (.gitignore should take care of this for the most part.)

This is a quick reference on how to use Doxygen to document our source code. More details can be found in the Doxygen manual.

Basic Code Documentation

Doc Comments

Doxygen uses a syntax that is somewhat similar to Javadoc. To create a documentation comment which will be parsed by Doxygen, use the following syntax:

/**
  comment text here
*/

Doc comments are considered to be documenting the code that is directly below them. Please document classes, functions, enums, and global constants. Doc comments may exist on their own as well, for example, if you want to add some extra documentation to a file. Preferably, doc comments should be in the header files; code that is in .cpp files should be considered private implementations. Please document things that only exist inside the .cpp files if it will help others understand the implementation later, but this documentation will not be picked up by Doxygen. It is also unnecessary to add doc comments in the .cpp file for things declared and documented in the header file.

Commands

You should use the following special commands where appropriate. Note that they can begin with either \ or @; the Doxygen manual uses \ but @ might be nicer for those familiar with Javadoc.

• @brief { brief description } (more info) - Gives a brief description of the thing being documented; this will be shown in lists of parameters and at the top of a documentation page for a class. If your documentation comment is longer than a sentence or two, please use this command on the first sentence and write the full documentation underneath.
• @param '['dir']' <parameter-name> { parameter description } (more info) - documents a method parameter. The dir can be in, out, or in,out, specifying the direction of the parameter (e.g. for output parameters you should use out). Most parameters will likely be in so the direction is optional in this case; please make sure to specify it for an output parameter though.
• @return { description of the return value } (more info) - documents a return value.
• @see { references } (more info) - Adds a cross-reference to something else. For most functions, just putting the name followed by () should be enough; for class methods, you may need to fully qualify them by using ClassName::methodName() or by adding some of the arguments inside the (). For more information on all the different kinds of references you can make, please see the manual.

Organization

Modules

Modules are a way to group related code in the documentation. When you create a module, it will be given a separate page in the documentation that can be accessed from the front page, where you can optionally put more information describing the module.

We should have a module for every subdirectory of the src folder in the repository. To create a module, add a doc comment somewhere at the top of the "main" file in your subdirectory (any file will work if there isn't a clear idea of which one is the "main" one) and have it contain the @defgroup <name> (group title) command (more info. The <name> parameter is an internal name for the module; please make this the same as the subdirectory name just to avoid confusion. The (group title) parameter is the human readable name of the module, and will be shown in the generated documentation. You should only need one @defgroup per subdirectory.

To specify which module your functions/classes belong to, you can add

/**
  @addtogroup <name>
  @{
*/

at the beginning of your code, and /** @} */ at the end. Anything between the two will be considered to be part of the module. If you are in the file with the @defgroup command, you can just add @{ to that doc comment instead of making a separate one with @addtogroup. There is some weirdness with namespaces, so if you have a namespace for your module, make sure these doc comments go inside the curly braces for the namespace.

Alternatively, you can add @ingroup <name> to the doc comments for every member of the module, but this is pretty tedious so it's recommended to use the @{/@} method.

For more details, please see the page Grouping in the Doxygen manual.

Example

/**
  @defgroup group1 This is a module.
  Optional description for this module here. It will go on the documentation page.
*/

namespace group1
{
/**
  @addtogroup group1
  @{
*/

/**
  @brief Class 1.
  This is an example class.
*/
class Class1
{
public:
    /**
      @brief method 1.
      This is an example method.
    */
    void method1();
};
/** @} */
// closes the module.

} // namespace group1