Using Doxygen

From Second Life Wiki
Jump to navigation Jump to search

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.