Using Doxygen for source documentation

Post date: May 18, 2011 10:55:25 PM

Installation

Download Doxygen here, about 9MB:

http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

Run the installation program, install wherever you like. I used the "Full Installation".

Download GraphViz here, about 57MB: (you will need to agree to the free license):

http://www.graphviz.org/Download.php

Run the installer, install wherever you like. I used the default options.

Generating documentation

In Windows, navigate to "Start > All Programs > doxygen" and select "Doxywizard".

Click "Select" and choose your project directory. Source code directory may be a subdirectory of this. It seems you must use the "Select" button instead of pasting in the path.

Fill out the fields for:

Click "Select..." to choose a source code directory. If you use subdirectories, check "Scan recursively".

Click "Select..." to choose a documentation directory. Create a "docs" subdirectory if you don't have one.

Click "Next" to begin entering "Mode" options.

Selected "All Entities" for the extraction mode.

Check "Include cross-referenced source code" to add color-coded source to documentation.

Select Optimize for C++ output.

Click "Next" to begin entering "Output" options.

Select "HTML", "plain HTML", "With search function".

Unselect "LaTeX".

Click "Next" to proceed to "Graphing" options.

Select "Use dot tool from the GraphViz package".

Select "Class diagrams", "Collaboration diagrams", "Overall Class hierarchy", "Include dependency graphs", "Included by dependency graphs", and "Call graphs".

Click the "Run" tab.

Click "Run doxygen". If it is disabled, you may have missed a step or specified an invalid directory.

After "*** Doxygen has finished" appears in the log, click "Show HTML output".

You can see a list of C++ class names by clicking the "Classes" tab in the HTML page. Click on a class name to see the documentation for that class, including inheritance diagram, function listing, and function call graphs.

After generating documentation, use "File" > "Save As", then navigate to docs directory. This will allow you to easily rebuild the documentation later.

The online documentation for doxywizard starts here:

http://www.stack.nl/~dimitri/doxygen/doxywizard_usage.html

You may use doxygen on the command line instead of using doxywizard. See this page:

http://www.stack.nl/~dimitri/doxygen/starting.html

Documenting source code

You will need to add formatted comments in your code for Doxygen to describe functions in more depth. See http://www.stack.nl/~dimitri/doxygen/docblocks.html for a guide to commenting for Doxygen.