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:
- function declarations
- defines
- structs
- enums
- typedefs
- global variables
- public classes
- public members
- public methods
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.