Monday, October 12, 2009

Doxygen Example

Doxygen is a documentation system for use with many languages, including C++, C, Java, and Python.

First, install Doxygen. Using Ubuntu, I installed the package with:
$ apt-get install doxygen
Next. enter the source directory of a project you're working on and run:
$ doxygen -g
That will create a config file named Doxyfile in the current directory. You can customize it, but we'll accept the defaults for now.

Now begin writing your documentation. Here's an example of documenting a simple C++ program:

#include <iostream>

using namespace std;

/**
* @brief Example class to demonstrate basic Doxygen usage
* @author MLA
*
* This is a simple class to demonstrate how Doxygen is used.
* It implements the Euclidean algorithm to compute the greatest
* common divisor of two numbers.
*/

class Euclid {
public:

/**
* Compute the greatest common divisor of two integers.
*
* @param a first integer
* @param b second integer
* @return greatest common divisor of a and b
*/
static const int gcd(const int a, const int b) {
if (0 == b) return a;
return gcd(b, a % b);
}
};

Finally, run doxygen, which will process the files and generate documentation in the html subdirectory:
$ doxygen
For more details, see the Doxygen homepage.