Doxygen Example

Doxygen is a tool that parses source code, finds specially-formatted comments, and produces nice-looking documentation files out of them. This repository is set up as an example that shows how Doxygen can be used.

For more information about how Doxygen works, see the official Doxygen website.

The Doxygen output for the project is available here.

This Repository

There are a few example C++ files in the src/ directory. To run the code, there is a run.sh file, which compiles the code and runs the result. An autoformat.sh script is also provided for completeness.

How to Install Doxygen

WSL Installation Instructions

If you are using a Windows computer, you should be using Windows Subsystem for Linux (WSL). There is no reason not to use it. It is vastly superior to the available Windows command prompt and to alternatives like GitBash. On top of that, you should be using WSL-TTY. If you use these, installing doxygen is as simple as following the steps below.

Doxygen can be installed with apt.

sudo apt-get install doxygen

In order for the pretty source tree graphs to be generated, you also need to install graphviz.

sudo apt install graphviz

Now you should be able to run Doxygen from the command line.

doxygen --version

Windows Installation Instructions

If for some reason you are not using WSL, you can follow these steps to install Doxygen.

Download and install Doxygen for Windows from the Doxygen website.
Add Doxygen to the Windows PATH.
Install the latest stable release of graphviz.
Add graphviz to the Windows PATH.
Modify the Doxyfile's DOT_PATH variable to point to the path of the graphviz executable.
Run doxygen.

How to Use Doxygen

There is a file called Doxyfile that controls how Doxygen will run. A new Doxyfile can be generated by using doxygen -g <filename> (leave the filename blank normally). This configuration file can be modified to change how Doxygen runs, and each project has its own Doxyfile.

To run doxygen, simply navigate to the project directory and run doxygen. It will look for source files, parse them, and generate output. For this project, a new folder called generated-docs will be created, but with the default configuration, the output will simply appear in the same folder as the Doxyfile. Inside the output folder or directly in the root folder, there will be an html folder, with a file called index.html in it. Open the index.html file with a web browser to view the documentation.

How to Deploy Doxygen to Gitlab

After each push, Gitlab scans your repository for a file called .gitlab-ci.yml. If that file is present, it will read the file and check that the file specifies a valid CI pipeline. If it is valid, then Gitlab looks for an available "runner." Runners can be other computers on the network, but in this case the runner is a docker container within the gitlab server virtual machine. Once a runner is available, Gitlab assigns a build for the project to the runner. The runner uses the pipeline from the .gitlab-ci.yml configuration file to know what actions to take. Part of that pipeline can include exporting build artifacts (like Doxygen html files or firmware .hex files).

For our Doxygen deploys, the configuration file will specify that doxygen is to be run, and that the built files are to be copied to the correct location for deployment. So in short, including the .gitlab-ci.yml will cause your deployed documents to update every time you push.

How to Comment for Doxygen

Doxygen comments start with /** and end with */, like this:

/**
 * Doxygen comments go here.
 *
 * The extra asterisks to the left are not required, but they are nice to have
 * visually.
 */
void exampleFunction(void);

A comment block like this will be recognized by Doxygen and will end up in the documentation. These blocks can contain differnt types of keywords, such as \brief, \param, and \return. An example C function is shown below using these. More examples can be found in the src/ directory of this repository.

/**
 * \brief Adds two numbers.
 *
 * This function takes two numbers, adds them, and then returns the result.
 * 
 * \param x The first number to add.
 * \param y The second number to add.
 * \return The sum of the two numbers.
 */
int add(int x, int y) {
    return x + y;
}

This Doxygen comment is complete, because it contains a \brief description of the function, it contains a detailed description beneath that, and it contains \param and \return descriptions for all its parameters and its return value.

Commenting for C/C++ with Header Files

In general, high-level comments (for documentation) should go in the header file, not the corresponding C file. Comments belong with declarations, not with definitions. For C++ classes, the .hpp file should be full of member declarations and Doxygen comments, while the corresponding .cpp file should consist mostly of just code.

Inline comments that are embedded inside of a function's body should of course go in the function definition itself (in the .cpp file). Functions that do not appear in the header file should be given Doxygen comments in the C file.

In short, there should never be 2 Doxygen comments for the same member, and putting the Doxygen comments in header files is preferred.

Grouping Members

You can also group members that go together. For example, you may have 5 constants that would require the same documentation:

#define MEW2KING 1
#define ARMADA 2
#define HUNGRYBOX 3
#define MANGO 4
#define PPMD 5

Instead of writing out the same documentation comment for each of these members, you can create a group like this:

/**
 * @{ \name Five Gods constants.
 */
/**
 * \brief Five Gods constants.
 *
 * These five constants represent the five gods.
 */
#define MEW2KING 1
#define ARMADA 2
#define HUNGRYBOX 3
#define MANGO 4
#define PPMD 5
/**
 * @}
 */

If the DISTRIBUTE_GROUP_DOC option is set to "YES" in the Doxyfile, then the documentation comment will be applied to all the member in the group. The \name tag also shows up as a heading over the group members.

This Repository's `Doxyfile`

The Doxyfile in this repository was generated using doxygen -g, and then edited in the following way:

Line 35:
PROJECT_NAME           = "Kyle's Doxygen Test"
Line 47:
PROJECT_BRIEF          = "This is just a test of Doxygen"
Line 54:
PROJECT_LOGO           = "./DiConIcon.ico"
Line 61:
OUTPUT_DIRECTORY       = "generated-docs"
Line 438:
EXTRACT_ALL            = YES
Line 363:
DISTRIBUTE_GROUP_DOC   = YES
Line 444:
EXTRACT_PRIVATE        = YES
Line 450:
EXTRACT_PACKAGE        = YES
Line 456:
EXTRACT_STATIC         = YES
Line 481:
EXTRACT_ANON_NSPACES   = YES
Line 759:
WARN_NO_PARAMDOC       = YES
Line 867:
RECURSIVE              = YES
Line 876:
EXCLUDE                = README.md
Line 998:
SOURCE_BROWSER         = YES
Line 1004:
INLINE_SOURCES         = YES
Line 1017:
REFERENCED_BY_RELATION = YES
Line 1023:
REFERENCES_RELATION    = YES
Line 1031:
REFERENCES_LINK_SOURCE = NO
Line 2334:
CALL_GRAPH             = YES
Line 2346:
CALLER_GRAPH           = YES

NOTE: The DiConIcon.ico file needs to be accessible at the given path (in this case in the root of the repository) in order for it to show up in the documentation pages.

Tips/Rules

Always use a \param tag for every parameter.
Always use a \return tag is the function returns a non-void value.
Always include a \brief description in addition to a long description.
Always put a Doxygen comment on every class, function, or macro in the source code.

nullromo/doxygen-example