Using Doxygen

Version: $Id: doxygen_howto.html,v 1.3 2001/07/06 12:42:50 nzc Exp $

Getting YOUR code documented

Currently we are running an experimental Doxygen setup. Contact the architecture board to get the documentation for your source scanned and generated.

How Doxygen works

Doxygen scans source code, looking for specifically formatted comments. Within the formatted comment block, you can out tags that indicate special types of documentation (e.g. parameter lists, return values). A full copy of the documentation can be found at the Doxygen homepage. There is a printed copy on Nzc's desk (in the Eindhoven office).

To use doxygen, precede a function declaration (or something else you wish to document) with a small piece of comment looking like this: 

/**
 * Foo or bar?
 * @param bar Value to be tested.
 * @retval 0 It was foo.
 * @retval 1 It was bar.
 */
int foobar(float bar);
After scanning, this function will get a nicely formatted chunk of hyperlinked documentation.

What to document

You can document anything you want, but specifically: If you write documentation, try to write from the reader's perspective: what does the reader want to know ? Mostly, the documentation will serve as a reference, so when someone refers to it, they will be in the process of writing code.

Useful tags

Apart from these tags, you can insert HTML-formatting in the comments. The list of allowed HTML commands can be found in the manual.

The manual also contains a Some of the more used are listed below, with a short explanation.