Table of Contents
Doxygen is a tool for generating formatted, browsable, and printable
documentation from specially-formatted comment blocks in source code.
This allows for developer documentation to be embedded in the files where
it is most likely to be kept complete and up-to-date. Doxygen currently supports C, C++, Java, and IDL, using two different
styles of documentation. Output formats include HTML,
L A T E X, XML, and
RTF; additional tools can be used to generate documentation in just about
any format imaginable, including hyperlinked PDF, man pages, PostScript,
compressed HTML (HTML Help), and Microsoft Word. While Doxygen appears similar to Javadoc or Qt-Doc, Doxygen offers a
wealth of additional features: - Highly portable (available for Unix, Windows, and MacOS X).
- Compatible with Javadoc, Qt-Doc, and KDOC.
- Automatically recognizes and generates cross-references.
- Can generate syntax-highlighted annotated source code.
- Converts from HTML tags to markup in L A T E X,
RTF, or man pages.
- Automatically generates class diagrams.
- Organize elements into groups, with specialized documentation.
- Include L A T E X-style mathematical formulas.
A number of high-profile projects use Doxygen extensively, and have
their source documentation available online: There are many, many more projects listed on the
" Projects that
use Doxygen " page.
Browsing though the generated documention of various projects is the
best way to get a feel for the flexibility of and style of Doxygen output. The Doxygen
download page offers binaries and source distributions for the package-happy, as well
as instructions for accessing the Doxygen CVS tree. If you encounter
problems while building or installing, be sure to consult the Doxygen
installation guide for known problems and workarounds. To generate documentation from your project, you'll need a Doxygen
configuration file, usually named Doxyfile . To do this, you can
have Doxygen generate a simple, basic configuration: doxygen -g filename Alternatively, you can use the doxywizard tool, which provides a GUI
interface for creating and editing the configuration file. doxywizard
is included with Doxygen, but you'll need to enable it during compilation
(if you compiled Doxygen from source) with the --with-doxywizard flag to configure . doxywizard requires Qt 2.x to run. A few options which I have found very useful to enable in the
configuration file are: | Option | Description | | EXTRACT_ALL=YES | Generate documentation for all elements, even if they don't have
documentation yet. | | JAVADOC_AUTOBRIEF=YES | When using Javadoc-style comments, treat the first sentence
as the brief description, and everything else as the detailed
description (this is the Javadoc standard behavior). | | SOURCE_BROWSER=YES | Generate a list of source files with cross-referenced entities. | | GENERATE_HTML=YES | Generate HTML documentation, including class diagrams. | | GENERATE_LATEX=YES | Generate LaTeX documentation. A makefile will also be generated so
that you can build PostScript, PDF, and DVI versions correctly. | | RECURSIVE=YES | Recursively search from the current directory for source files. | | GENERATE_TREEVIEW=YES | For HTML output, generate a sidebar index. | More options can be found in the configuration
section of the Doxygen manual . The good news is that if you already are familiar with Javadoc or Qt-Doc,
you already know the basics of writing Doxygen documentation. For those
unfamiliar with either system, the basic idea is that you place
specially-formatted comments immediately above anything you want to
document (such as a class, struct, method, field, etc.). Javadoc-style example: /**
* Method documentation.
* @param x The parameter.
* @return The return value.
* @see anotherFunction()
*/
/** Single-line documentation. */
/// Single-line documentation. Qt-style example: /*!
Method documentation.
\param x The parameter.
\return The return value.
\sa anotherFunction()
*/
/*! Single-line documentation. */
//! Single-line documentation. In addition, Doxygen also lets you place documentation after an
element, useful for quickly documenting enums, structs, and member
variables: int a; ///> Javadoc-style.
char b; //!> Qt-style. For C and C++ files, you can place the documentation for your
elements in either the header or the main file; Doxygen will match up
declarations with the actual code. Include the following markup commands in your documentation to denote
special items. I'm using Javadoc-style here; for the most part,
the Qt-style equivalents are the same keyword, but starting with a
backslash rather than an at-symbol. | Markup | Description | | @param var desc... | Document a parameter called var to a function or method. | | @return desc... | Document the return value of a function. | | @see elem | Add a "see also" link to elem , which can be a function,
class, or any other documented identifier. | | @author name | Indicate the author of an element. | | @author name | Indicate the author of an element. | | @version ver | Indicate the version of an element. | | @todo desc... | Leave a note about unfinished work. | | @warning desc... | Leave a warning. | See the Special
Commands Reference for a complete list of markup commands. |
Using Doxygen 
