Notes

This is just a sample project for seeing how Doxygen works.

Steps

Setup Doxygen configuration

doxygen -g <config file (defaults to Doxyfile)

Fine-tune Configuration

1. Set PROJECT_NAME to the project name.
2. Set INPUT to the subdirectories containing documented files. If left empty Doxygen will just scan the current directory; however, it’s better to be explicit. If there is a directory containing dependencies, you may want to include that directory if it is documented. Even if the dependencies are not documented, Doxygen may be able to piece together object relationships to give you something to work with.
3. Set RECURSIVE to YES. This means that subdirectories within those specified in INPUT will be searched. I feel that this is a reasonable default to have. If a situation arises where you need to exclude certain subdirectories, you can use the EXCLUDE key to do so.
4. Make a main page. In modern versions of Doxygen, you can use the USE_MDFILE_AS_MAINPAGE key to specify a markdown file that will be used as the main landing page. Note that in order for the file to be loaded, however, you need to add the file to the INPUT field.

Writing Comments

Note that in order for “globally”-scoped entities to show up in the Doxygen output, the file or namespace containing the entity must be documented. This can be done with a comment like the following:

/**
 * @file header1.hpp
 * @brief This file declares prototypes for some functions.
 */

Otherwise, Doxygen will only render the entity if the EXTRACT_ALL key is equal to YES; this tells it to extract subentities from entities that are not explicitly documented on their own.

Function comments should resemble the following. My opinion is that these should only appear in header files, but this may be up for discourse.

/**
 * @brief Yields the length of a string subtracted by an integer
 *
 * @param some_string This string represents someone's name.
 * @param some_integer This integer represents someone's age.
 * @return The length of `some_string` subtracted by `some_integer`
 */
int some_int_function(std::string some_string, int some_integer);

Class comments should resemble the following:

/**
 * @class MyClass
 * @brief This class represents a model in the MVC framework.
 */
class MyClass {
   ...
}

Namespace comments should resemble the following:

/**
 * @namespace systemantics
 * @brief This namespace contains some information.
 */
namespace systemantics {
   ...
}

NOTE: for namespace comments, it’s likely a good idea to have them all in one central place rather than documenting them alongside classes and other members. The reason for this is that namespaces can span multiple files, and thus it may not be clear where the documentation for the namespace should go. Therefore, by keeping namespace documentation in one central place, we do not have to worry about where a given namespace should be documented.