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 customized main page, linking between similar functions, automatic bug/todo lists, insert latex equations and more!
Doxygen Quick Reference
A quick reference of the most popular Doxygen keywords for documenting source code:
|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.
EXAMPLE: A full working Doxygen example in C++ can be found at https://github.com/gbmhunter/CppTemplate. The Doxygen configuration file generates documentation for this C++ template project and the HTML documentation output can be viewed on GitHub pages at https://gbmhunter.github.io/CppTemplate/index.html.
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.
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 are good for…grouping things together.
Doxywizard is a Windows GUI for using Doxygen. 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).
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.
This work is licensed under a Creative Commons Attribution 4.0 International License .