Doxygen

Overview

Doxygen is an open-source program for documenting code. It is commonly used to build documentation from source files which have special identifiers added to help generate useful documentation. Doxygen supports many languages (including C, C++, C#, Java, Python, VHDL, PHP and others…), however only C/C++ documentation is covered here. As of 2016, it is guessed to be the most popular method for documenting C/C++ code.

It is essentially a program which looks through your source code and extracts information about functions, variables, enumerations, defines and almost everything else, including special comments and identifies that you place in the code, and compiles it into a nice looking html, pdf, or latex document. With the right commands, you can create a customised main page, linking between similar functions, automatic bug/todo lists, insert latex equations and more!

Screenshot of the html documentation that Doxygen generates with properly commented code.
Screenshot of the html documentation that Doxygen generates with properly commented code.

Doxygen Quick Reference

A quick reference of the most popular Doxygen keywords for documenting source code:

Command Description
@brief  Gives a brief description of the object (variable/function/enum/struc/define) that will appear beside the name of the object in the index at the top of the pages that Doxygen produces.
@details  A more detailed description of the object that will appear below the index at the top of the page.
@param  Used to describing parameters (arguments) into a function.
@returns  Used to describe the return value from a function (if any). Has the same functionality as @return.
@sa  Used to refer to other objects (acronym for ‘see also’).
@public  Defines the object as public. Useful in C programming since the visibility is not usually implicit.
@private  Define the object as private. Useful in C programming since the visibility is not usually implicit.
@todo  I add it anywhere where I want to come back a change something at a later date. Doxygen automatically finds these notes and combines them into a “To Do” page in the documentation!
@debug  I add this wherever I have added code which is specifically for debugging.

How To Use Doxygen

To use Doxygen, you first place appropriate documenting comments in the source files. The comments must be made with a special comment operator that Doxygen recognizes. Normally, the documentation comments are placed directly before the object (e.g. function, variable) that you want to document. Then to generate the documentation, run Doxygen from the command-line in Linux, or Doxywizard on Windows, and it will make some nicely formatted HTML or Latex (PDF) documentation.

Example File Header

I normally use the following file headers when documenting with Doxygen.

The Main Page

The first time you use Doxygen, you open up your newly created documentation and discover that the first page (aka the main page or landing page) is blank. This is because Doxygen designed it this way, and to put stuff on it, you have to specifically tell Doxygen to do so. This can be done with the  @mainpage  command. The following example adds a main page with two sections.

Note that this code to create a main page doesn’t have to be anywhere special, it can be in of the files that Doxygen parses during document creation.

Doxygen “Escapes” For Comment Blocks

Doxygen supports a number of “escapes”, ways of signalling that a code comment should be parsed by the Doxygen engine.

All of the above comment blocks are treated identically by Doxygen.

There is also provision for putting documentation after objects such as variables and function parameters. This can be done by adding a < to the end of the Doxygen escape sequence, e.g.:

 

Groups

Groups are good for…grouping things together.

Groups are good for grouping bunches of related variables together.

Doxywizard Settings

Doxywizard is a Windows GUI for using Doxygen. Desired Extraction Mode: Documented Entities Only Optimise For: C or PHP output Output format: HTML (with navigation panel, search function) Setting EXTRACT_PRIVATE = 1 and EXTRACT_STATIC = 1 results in doxygen including all commented objects into the documentation, not just the ones that it deems public or accessible from other files (static). I find this to be much more useful than to exclude them, as without these objects present in the documentation it can leave the reader wondering how on earth your code works (C doesn’t have the nice public interface structure that object orientated programming has). The following picture shows the two options selected when using the Doxygen GUI (Doxywizard).

 
Selecting 'EXTRACT_PRIVATE' and 'EXTRACT STATIC' in the Doxygen GUI.
Selecting ‘EXTRACT_PRIVATE’ and ‘EXTRACT STATIC’ in the Doxygen GUI.
 

Make sure to save your configuration file (doxyfile, no extension) somewhere with the source code so you can run it again and doxygen will remember the settings.

More Examples

See some of my C code templates/examples on BitBucket for more Doxygen commenting. The FreeRTOS-Uart project is a good example.