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 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

My favourite keywords for documenting C code are:

  • @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.
  • @sa – Used to refer to other objects (acronym for ‘see also’).
  • @param – Used to describing inputs to a function.
  • @returns – Used to describe the return value from a function (if any). Has the same functionality as @return.
  • @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 documentating comments in the source files. The comments must be made with a special comment operator that Doxygen recognises. 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.

Groups

Groups are good for…grouping things 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.