Software Documentation with Doxygen

This is a good practice to always have up-to-date software documentation. However, there can be discrepancy between the source code and the documentation over time and maintenance may be an issue. This is where Doxygen,  a “Source code documentation generator tool”, may be handy as it will automatically generate documentation based on the comments in the source code. In order for Doxygen to work, all developers will have to follow the same source code format in all source files,which is in itself also a plus since it will make the code and especially comments in this case more consistent.

We’ll just show to quickly generate html and pdf documentation using a sample program we’ll call cnxapp.

So here’s the code for this “application”

 

#include <stdio.h>

/**
Function1 description

@param iArg1
First param description
@param iArg2
Second param description

@return
0 – Success
-1 – Failure
*/

int function1(int iArg1, int iArg2) {
return 0;
}

/**
Function2 description

@param pchString
String to handled by the function
*/
void function2(char *pchString) {

}

int main () {
function1(1, 1);
function2(“hello\n”);
return 0;
}

As you can see, all comments start with a line with /** and finish with a line with */, this is the formatting required by doxygen to generate the documentation based on the source code.

We also added @param and @return to respectively automatically generate a Parameter entry and Return entry in the documentation.

Once the source code is well formatted, the first thing to do is to create a config file for doxygen using the following command line in the source directory:

doxygen -g cnxapp.conf

This will create cnxapp.conf automatically with some default values.

Then we edited it manually to add the application name, version and output directory:
PROJECT_NAME           = CNXAPP
PROJECT_NUMBER         = 1.00
OUTPUT_DIRECTORY       = doc

and some other settings to force creating some part of the documentation:
ALWAYS_DETAILED_SEC    = YES
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTRACT_ALL            = YES
EXTRACT_STATIC         = YES

Once this is done, just run doxygen cnxapp.conf, and it will create a doc directory with the html documentation.
You can check the documentation created for our little app or go directly to cnxapp.c functions documentation.

doxygen also support creating pdf documents. You’ll need latex for this to work. This is installed in most of Linux distributions.  If you don’t have it, download http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz, extract it and run ./install-tl as root or sudoer and be very patient…

Go to the doc/latex directory and type make pdf in order to create the PDF version of the documentation.

This is only a quick start guide as Doxygen has obviously many more features available and I encourage you to visit Doxygen website for further information.