Difference between revisions of "Using Doxygen"
Rob Linden (talk | contribs) (Edited version of the document copied from our internal wiki) |
Rob Linden (talk | contribs) |
||
| Line 1: | Line 1: | ||
==Introduction == | ==Introduction == | ||
| Line 42: | Line 41: | ||
The Linden Lab [[Coding Standard|coding standard]] specifies using Doxygen comments in code. | The Linden Lab [[Coding Standard|coding standard]] specifies using Doxygen comments in code. | ||
[[Category:Open Source Portal]] | |||
Latest revision as of 09:47, 8 April 2009
Introduction
Doxygen is a utility that extracts documentation from source files. It can generate HTML output and/or PDF output as well as a few other types. In addition to basic information gathered from non-comment portions of the source files (i.e. function names, parameters, etc.), it attempts to pick up comments and place them in the documentation where appropriate. Additionally it recognizes a special format of comment in order to give a great deal of control over the generated documentation.
Installing Doxygen and helpers
In addition to Doxygen itself, you may want to install GraphViz because Doxygen can use its graph generator tool (dot) to include some nice dependency graphs in the output. You can skip installation of GraphViz, but you won't get the nice graphs.
To generate PDF output from Doxygen, install the tetex package.
Debian Linux
If you're on a Debian Linux, you can install Doxygen and the dot graph generator (that Doxygen uses) like this:
sudo aptitude install doxygen graphviz
Mac OS X MacPorts
If you're using Mac OS X and MacPorts, you can install Doxygen and the dot graph generator (that Doxygen uses) like this:
sudo port install doxygen graphviz
Cygwin / Windows
For Cygwin, run the Cygwin installer and install both Doxygen and GraphViz.
Running Doxygen
The Doxygen manual covers running Doxygen in some detail. Doxygen gets all of its configuration information from a config file,which has a seemingly endless list of options. For example, if you want to run Doxygen on only a couple of files (such as the ones you're editing -- to see if you got the Doxygen-specific comments right), you have to edit the configuration file before you run Doxygen.
WARNING: running Doxygen on a lot of files can take quite a while. This can be a very annoyingly large amount of time depending on how you've configured it and how many files are involved. It almost seems like the time to run goes up exponentially as the number of files being processed increases.
Using Doxygen
Doxygen manuals:
Source code comments
Everyone new to Doxygen should look at the Documenting the code section of the Doxygen manual. It explains the formatting of the special Doxygen comments and gives several examples.
The Linden Lab coding standard specifies using Doxygen comments in code.