CS 242 Spring 2012 : Commenting Code With Doxygen

This page last changed on Jan 12, 2012 by conadmin.

A brief doxygen tutorial

by Charlie Meyer – March 2008

As you have seen so far this semester, commenting code is a critical component to the software development process, but doing it in a standard fashion allows for automated tools to parse your source files and produce professional looking documentation that can accompany the finished project.

What is doxygen?

Doxygen is a tool that can read in source code files (written in c, c++, java, python, and c# as well as others), parse comment blocks, and produce elegant output in a variety of formats including html, pdf, rtf, and latex. In order for the program to function properly, it is important that the source files are marked up with special comment syntax. Doxygen can be downloaded for windows, linux, and mac from here. It is also available in many linux distrobution’s package management systems.

Getting started

The first step in the process is to create a configuration file for your project. This file will contain information that doxygen will require so that it can properly create output. On the command line in the root of your project directiory, execute the following:

doxygen -g

This will create a file called Doxyfile. Using a text editor, open up Doxyfile and edit the parameters to fit your project. Read each of the comment blocks before each of the configuration options to learn how to set each option properly. Although this task might seem a bit lengthy, many of the options have already been set to their default values, so you do not have to worry about changing them unless you explicity want to.

Documenting your code

Doxygen comments are in the form of /** <comments> */ for a multiline comment, or for a single line comment, /// . Anything after a doxygen style comment opening will be parsed by doxygen when creating output. Here is an example of a sample class properly documented with doxygen style comments:

/**
* @file test.h  
* @author Charlie Meyer  
* @date 3-30-08  
*/ 
class Test {   

/// documentation before a variable   
int x;    

int y; ///< this is how you comment after a variable, on the same line    

/**   
* Takes two integers and adds them together   
* @param a the first integer in the addition   
* @param b the second integer in the addition   
* @return the value when the two integer parameters are added together   
*/   
int add(int a, int b);    

/**  
* Takes two integers and subtracts them   
* @param a the first integer in the subtraction   
* @param b the second integer in the subtraction   
* @return the value when the two integer parameters are subtracted   
*/   
int subtract(int a, int b);    

/**   
* this method tests the add and subtract functions   
* @see add()   
* @see subtract()   
*/
void unitTest(); 

};

From this example, many of the basic formatting rules are evident. Each comment block starts with a basic description of the code to follow, then several lines with directives. The @param directive gives information about parameters to a function, you should have one @param line for each parameter to each function. The @return directive is used to give a breif description of what the function you are commenting returns. The @see directive will put hyperlinks in the finished output for the function you are commenting to the documentation for the functions which the @see directive refers to. This is especially useful for tests, so when reading the documentation, it is very easy to tell which tests are testing which other functions. Each of the directives at the top of the source file are self explanitory.

Generating the documentation

Once your code is properly commented, just run the command

doxygen

in the directiory which contains Doxyfile, and presto, documentation is generated based off of your configuration and the markup in the source files

Document generated by Confluence on Mar 29, 2012 02:55

  1. No comments yet.

  1. No trackbacks yet.