Usage Notes of

Doxygen
(a computer program documentation generator)

William.L
Index
Introduction..................................................................................................................................................... 1
Tools.................................................................................................................................................................. 3
Linux platform ........................................................................................................................................ 3
Windows platform .................................................................................................................................. 4
Generate Diagrams/Graphs ........................................................................................................................... 9
Ubuntu ..................................................................................................................................................... 9
CentOS 6 .................................................................................................................................................. 9
MS Windows.......................................................................................................................................... 10
Configuration File......................................................................................................................................... 12
Documenting the Code ................................................................................................................................. 16
Special Command ................................................................................................................................. 16
Putting documentation after members ............................................................................................... 19
Documentation at other places ............................................................................................................ 22
Example – HTML output ............................................................................................................................. 25
Introduction
When viewing source codes written by others or sharing codes to others, it would be better for readers if
there have documents to comment or explain codes and show architecture(relationship of each part, such as
files, modules, packages, functions, classes, in codes) using graph or diagram. This may let readers get idea
(overview, a big picture) of codes quickly.

There have many tools to generate documents of source codes by adding special markings in comment
blocks, this kind of tool is called Document Generator. For a programmer, if he or she can add comments
while coding, the work to document codes could be accomplished when code is done, it would save much
time compared to that adding comments after code is done. Comments about code's implementation are
called Implementation comments. Comments describe the specification of the code, from an
implementation-free perspective to be read by developers who might not have the source code at hand, are
called Documentation comments. Tools such as JavaDoc, Doxygen, DOC++, Qt Qdoc(for Qt Project
itself only) are well-known. Doxygen is used to generate documents for Desktop App Chooser program..

Doxygen (http://www.doxygen.org/) is for generating documentation from annotated C++ sources, but it
also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL
(Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D. It runs on
most Unix systems as well as on Windows and Mac OS X.

Doxygen is written in Qt (http://qt-project.org/). Initially doxygen was specifically designed to be used for
projects that make use of Troll Tech’s Qt toolkit. So it is ‘Qt-compatible’:
doxygen can read the documentation contained in the Qt source code and create a class browser that
looks quite similar to the one that is generated by Troll Tech. Doxygen understands the C++
extensions used by Qt such as signals and slots and many of the markup commands used in the Qt
sources.

How did the name "Doxygen" come from? From Doxygen FAQ of the official site, its solution is that:
" Doxygen got its name from playing with the words documentation and generator.

documentation -> docs -> dox

generator -> gen

At the time I was looking into lex and yacc, where a lot of things start with "yy", so the "y" slipped in
and made things pronounceable (the proper pronouncement is Docs-ee-gen, so with a long "e")."
Doxygen FAQ link: http://www.stack.nl/~dimitri/doxygen/manual/faq.html

It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in
LATEX) from a set of documented source files. There is also support for generating output in RTF
(MS-Word), PostScript, hyperlinked PDF, compressed HTML(.chm), and Unix man pages. The
documentation is extracted directly from the sources, which makes it much easier to keep the documentation
consistent with the source code.
The following figure shows the relation between the tools and the flow of information between them.

( From doxygen site - http://www.stack.nl/~dimitri/doxygen/manual/starting.html )

Doxygen looks at the file's extension to selects the proper parser to parse a file. Extension types
recognized by doxygen is listed in http://www.stack.nl/~dimitri/doxygen/manual/starting.html
Tools
The executable doxygen is the main program that parses the sources and generates the documentation.

To generate a manual for your project you typically need to follow these steps:
<1> Document your source code with special documentation blocks , or called special command blocks.
See http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html .

<2> Generate a template configuration file by running doxygen with the -g option:

doxygen -g <config_file>

<3> Edit the configuration file so it matches your project. In the configuration file you can specify the input
files and a lot of optional information.

<4> Let doxygen generate the documentation, based on the settings in the configuration file. The default
output directory is the directory in which doxygen is started.

doxygen <config_file>

<5> If you have a configuration file generated with an older version of doxygen, you can upgrade it to the
current version by running doxygen with the -u option.

doxygen -u <config_file>
All configuration settings in the original configuration file will be copied to the new configuration file.
Any new options will have their default value. Note that comments that you may have added in the
original configuration file will be lost.

More detailed information about doxygen tool is here:

http://www.stack.nl/~dimitri/doxygen/manual/doxygen_usage.html

Optionally, the doxywizard tool which is a graphical front-end (GUI) written in Qt can be used for
editing the configuration file that is used by doxygen and for running doxywizard in a graphical
environment. More detailed usage information about doxywizard is here:
http://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html

Linux platform
To use package manger of the Linux distro you are using now to search and install Doxygen program.
In Ubuntu / Debian, you could use APT/Aptitude tool.
In RedHat you could use RPM and use YUM for Fedora / CentOS.
Windows platform
Download Doxygen program for Microsoft Windows from the following site and install it:
http://www.stack.nl/~dimitri/doxygen/download.html

The GUI front of Doxygen, Doxywizard, could be found in the install path shown as below :

If you use the GUI frontend tool, you needs not to have Doxygen configuration file, cause to that all
configuration items are list in the GUI tool and you just to check/uncheck it for truning on/off the
features of output documentation.

To invoke "doxywizard.exe" and configure the output style you want as below snapshots.
Note:
For outputting diagrams/graphs in the documentation, you MUST install GraphViz tool(see the next
chapter) and configure the path to its executables in Path environment variable in advance.

More detailed configuration items could be found in “Expert” tab/pane.

After configuring, you could view all configurations by clicking “Show configuration” button in “Run”
tab/pane. If you want to save these configurations into a file(e.g. configuration file), just click “Save
log…” button to invoke file dialogue to choose saving folder and file name.

Note: the saved configuration file could be used in the command line way stated in the beginning of this
chapter.
To start Doxygen tool for parsing source codes and generating documentation into the designated output
folder by clicking “Run doxygen” button in “Run” tab/pane. You could see generating process when
Doxygen is running.
If Doxygen tool runs successfully, you could see the output documentation in the output directory you
designated.
Generate Diagrams/Graphs
Doxygen can use the "dot" tool from GraphViz (Graph Visualization Software) to generate more
advanced diagrams and graphs. GraphViz is an open-source, cross-platform graph drawing toolkit and can
be found at http://www.graphviz.org/

To install GraphViz tool, run below commands in two Linux distro separately:

Ubuntu
sudo apt-get -y install graphviz

The below screenshot shows installed graphviz tool in Synaptic Package Manager program.

CentOS 6
$ su
# yum -y install graphviz
(prompt $ is for Regular user and prompt # is for Super user)

To view details about GraphViz package, run command:

# rpminfo graphviz
If you have the "dot" tool in the path, you can set tag HAVE_DOT to YES in the configuration file to let
doxygen use it.

MS Windows
Below instructions are for Microsoft Windows.
1) Download graphviz for Windows from the following site:
http://www.graphviz.org/Download_windows.php

2) Install graphviz through MSI executable or extract ZIP archive to the folder you want.

3) Set the path to graphviz executables in Path environment variable

Right clicking My Computer -> Content -> Advanced System Setting -> Environment Variables ->
Select Path environment variable and add the path to graphviz executables (here using “C:\Program
Files\Graphviz2.38\bin” for example.)
Configuration File
A configuration file is a free-form ASCII text file with a structure that is similar to that of a Makefile, with
the default name Doxyfile. It is parsed by doxygen tool.

The file essentially consists of a list of assignment statements.

* Each statement consists of a TAG_NAME written in capitals, followed by the equal sign (=) and one
or more values.
* If the same tag is assigned more than once, the last assignment overwrites any earlier assignment.
* For tags that take a list as their argument, the += operator can be used instead of = to append new values
to the list.
* Values are sequences of non-blanks.
* If the value should contain one or more blanks it must be surrounded by quotes ("..."). Multiple lines
can be concatenated by inserting a backslash (\) as the last character of a line.
* Environment variables can be expanded using the pattern $(ENV_VARIABLE_NAME).
* The statements in the file are case-sensitive.

The file may contain tabs and newlines for formatting purposes.

The default encoding used for all characters in the configuration file is UTF-8 and it could be changed by
setting the tag DOXYFILE_ENCODING. Doxygen uses libiconv (or the iconv built into libc) for
transcoding. See http://www.gnu.org/software/libiconv for the list of possible encodings.

Here listing some tags usually used in project:

Tag Name Description Default Depending Tag
Value
PROJECT_NAME A single word (or a sequence of
words surrounded by
double-quotes) that should
identify the project.
PROJECT_NUMBER Project or revision number
PROJECT_BRIEF To provide an optional one line
description for a project that
appears at the top of each page
and should give viewer a quick
idea about the purpose of the
project.
OUTPUT_DIRECTORY To specify the (relative or
absolute) path into which the
generated documentation will
be written.
OUTPUT_LANGUAGE To specify the language in English
 which all documentation
generated by doxygen is
written.
INPUT To specify the files and/or If this tag is
directories that contain empty the
documented source files. current
You may enter file names like directory is
myfile.cpp or directories like searched.
/usr/src/myproject.
Separate the files or directories
with spaces.
RECURSIVE Be used to specify whether or No
not subdirectories should be
searched for input files as well.
EXTRACT_ALL Assume all entities in No
documentation are
documented, even if no
documentation was available.
EXTRACT_ANON_NSPACES Include the members of No
anonymous namespaces
EXTRACT_LOCAL_CLASSES Include classes (and structs) Yes
defined locally in source files.
EXTRACT_LOCAL_METHODS Include local methods, which No
are defined in the
implementation section but not
in the interface
EXTRACT_PRIVATE Include private members of No
a class
EXTRACT_STATIC Include static members of a No
class
SORT_MEMBER_DOCS Sort the (detailed) Yes
documentation of file and
class members alphabetically
by member name.
GENERATE_HTML Generate HTML output Yes
HTML_HEADER GENERATE_HTM
HTML_FOOTER A footer typically contains the L
author of the document,
copyright information, links to
terms of use, contact
information, etc.
HTML_OUTPUT Specify output folder
HTML_FILE_EXTENSION Specify the file extension .html
GENERATE_TREEVIEW No
HAVE_DOT To use dot tool to generate No
diagrams and graphs
CALL_GRAPH Generate a call dependency No HAVE_DOT
graph for every global function
or class method.
CALLER_GRAPH Generate a caller dependency No
graph for every global function
or class method
GENERATE_LEGEND Yes
GRAPHICAL_HIERARCHY Yes
DIRECTORY_GRAPH Yes
UML_LOOK No
UML_LIMIT_NUM_FIELDS Threshold limits the number of 10
items for each type to make the
size more manageable.
Set this to 0 for no limit.
Minimum value: 0
Maximum value: 100
CLASS_GRAPH Yes
COLLABORATION_GRAPH Yes
GENERATE_LATEX Yes

For a small project consisting of a few C and/or C++ source and header files, you can leave INPUT tag
empty and doxygen will search for sources in the current directory.

If you have a larger project consisting of a source directory or tree you should assign the root directory or
directories to the INPUT tag, and add one or more file patterns to the FILE_PATTERNS tag (for instance
*.cpp *.h). Only files that match one of the patterns will be parsed (if the patterns are omitted a list of source
extensions is used). For recursive parsing of a source tree you must set the RECURSIVE tag to YES.

If you start using doxygen for an existing project (thus without any documentation that doxygen is aware
of), you can still get an idea of what the structure is and how the documented result would look like. To
do so, you must set the EXTRACT_ALL tag in the configuration file to YES. Then, doxygen will pretend
everything in your sources is documented. Please note that as a consequence warnings about undocumented
members will not be generated as long as EXTRACT_ALL is set to YES.

If the EXTRACT_ALL option is set to NO in the configuration file (the default), then doxygen will only
generate documentation for documented members, files, structs, classes and namespaces.
To analyze an existing piece of software it is useful to cross-reference a (documented) entity with its
definition in the source files. Doxygen will generate such cross-references if you set the
SOURCE_BROWSER tag to YES. It can also include the sources directly into the documentation by
setting INLINE_SOURCES to YES (this can be handy for code reviews for instance).

More detailed usage information about configuration file could be found in:
http://www.stack.nl/~dimitri/doxygen/manual/config.html
Documenting the Code
For members, structs, classes and namespaces there are basically two options to document codes:
1. Place a special documentation block in front of the declaration or definition of the member, struct,
class or namespace. For file, struct, class and namespace members it is also allowed to place the
documentation directly after the member.
2. Place a special documentation block somewhere else (another file or another location) and put a
structural command in the documentation block. A structural command links a documentation
block to a certain entity that can be documented (e.g. a member, struct, class, namespace or file).

Files can only be documented using the second option, since there is no way to put a documentation block
before a file. Of course, file members (functions, variables, typedefs, defines) do not need an explicit
structural command; just putting a special documentation block in front or behind them will work fine.

The text inside a special documentation block is parsed before it is written to the HTML and/or LaTeX
output files.
During parsing the following steps take place:
* Markdown formatting is replaced by corresponding HTML or special commands.
* The special commands inside the documentation are executed.
* If a line starts with some whitespace followed by one or more asterisks (*) and then optionally more
white space, then all whitespace and asterisks are removed.
* All resulting blank lines are treated as a paragraph separators. This saves you from placing
new-paragraph commands yourself in order to make the generated documentation readable.
* Links are created for words corresponding to documented classes (unless the word is preceded by a %;
then the word will not be linked and the % sign is removed).
* Links to members are created when certain patterns are found in the text. This link is called Automatic
Link ( http://www.stack.nl/~dimitri/doxygen/manual/autolink.html .)
* HTML tags that are in the documentation are interpreted. More information could be found in
http://www.stack.nl/~dimitri/doxygen/manual/htmlcmds.html .

The following doxygen documenting commands are used in comment blocks for C-like languages(C, C++,
C#, Objective-C, PHP, Java).

Special Command
A special documentation block is a C or C++ style comment block with some additional markings, so
doxygen knows it is a piece of documentation that needs to end up in the generated documentation.

For each code item there are two (or in some cases three) types of descriptions, which together form the
documentation: a brief description and detailed description, both are optional.

For methods and functions there is also a third type of description, the so called ”in body” description,
which consists of the concatenation of all comment blocks found within the body of the method or
function.

Having more than one brief or detailed description is allowed (but NOT recommended, as the order in
which the descriptions will appear is not specified).

As the name suggest, a brief description is a short one-liner, whereas the detailed description provides
longer, more detailed documentation. An ”in body” description can also act as a detailed description or
can describe a collection of implementation details. For the HTML output brief descriptions are also use
to provide tooltips at places where an item is referenced.

There are several ways to mark a comment block as a detailed description:

<1> JavaDoc style

/**
* ... text ...
*/

<2> Qt style(e.g. Qdoc, )

/*!
* ... text ...
*/

In both cases the intermediate * (asterisk)’s are optional, so below example is also valid.

/*!
... text ...
*/

<3> A block of at least two C++ comment lines, where each line starts with an additional slash or an
exclamation mark.

/// //!
/// ... text ... or //! ... text ...
/// //!

<4> To make their comment blocks more visible in the documentation.

/********************************************//**
* ... text
***********************************************/
 (note the 2 slashes to end the normal comment block and start a special comment block)
or

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

For the brief description there are also several possibilities:

<1> One could use the \brief command with one of the above comment blocks. This command ends at
the end of a paragraph, so the detailed description follows after an empty line.

/*! \brief Brief description.

* Brief description continued.
*
* Detailed description starts here.
*/

<2> If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then using JavaDoc style
comment blocks will automatically start a brief description which ends at the first dot followed by a
space or new line.

/** Brief description which ends at this dot. Details follow

* here.
*/

The option has the same effect for multi-line special C++ comments:

/// Brief description which ends at this dot. Details follow

/// here.

<3> To use a special C++ style comment which does not span more than one line.

/// Brief description.

/** Detailed description. */
or

//! Brief descripion.

//! Detailed description

//! starts here.
(Note the blank line in the last example, which is required to separate the brief description from the
block containing the detailed description. The JAVADOC_AUTOBRIEF should also be set to NO
 for this case.)

If you have multiple detailed descriptions (as below example), they will be joined. Note that this is also the
case if the descriptions are at different places in the code! In this case the order will depend on the order in
which doxygen parses the code.

//! Brief description, which is

//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
*/

Furthermore, if there is one brief description before a declaration and one before a definition of a code
item, only the one before the declaration will be used. If the same situation occurs for a detailed
description, the one before the definition is preferred and the one before the declaration will be ignored.

Unlike most other documentation systems, doxygen also allows you to put the documentation of members
(including global functions) in front of the definition. This way the documentation can be placed in the
source file instead of the header file. This keeps the header file compact, and allows the implementer of the
members more direct access to the documentation.

Putting documentation after members

If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to
place the documentation block after the member instead of before. For this purpose you have to put an
additional < marker in the comment block. Note that this also works for the parameters of a function.

int var; /*!< Detailed description after the member */

(This block can be used to put a Qt style detailed documentation block after a member.)
or
int var; /**< Detailed description after the member */

or

int var; //!< Detailed description after the member

//!<
or

int var; ///< Detailed description after the member

///<

Most often one only wants to put a brief description after a member. This is done as follows:
 int var; //!< Brief description after the member
or

int var; ///< Brief description after the member

For functions one can use the @param command to document the parameters and then use [in], [out],
[in,out] to document the direction. For inline documentation this is also possible by starting with the
direction attribute, e.g.

void foo(int v /**< [in] docs for input parameter v. */);

Note that these blocks have the same structure and meaning as the special comment blocks, only the <
indicates that the member is located in front of the block instead of after the block.

[Warning]
These blocks can only be used to document members and parameters. They cannot be used to document
files, classes, unions, structs, groups, namespaces and enums themselves. Furthermore, the structural
commands are NOT allowed inside these comment blocks.

An example of C++ code using the Qt style:

 //! A test class.
/*!
A more elaborate class description.
*/
class Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
.....................................................
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};

The one-line comments contain a brief description, whereas the multi-line comment blocks contain a more
detailed description.

The brief descriptions are included in the member overview of a struct, class, namespace or file and are
printed using a small italic font (this description can be hidden by setting BRIEF_MEMBER_DESC to
NO in the configuration file).

By default the brief descriptions become the first sentence of the detailed descriptions (but this can be
changed by setting the REPEAT_BRIEF tag to NO). Both the brief and the detailed descriptions are
optional for the Qt style.

By default a JavaDoc style documentation block behaves the same way as a Qt style documentation block.
This is not according the JavaDoc specification however, where the first sentence of the documentation
block is automatically treated as a brief description. To enable this behavior you should set
JAVADOC_AUTOBRIEF to YES in the configuration file. If you enable this option and want to put a dot
in the middle of a sentence without ending it, you should put a backslash and a space after it as below
example.

/** Brief description (e.g.\ using only a few words). Details follow. */

Here is the same piece of code as shown above, this time documented using the JavaDoc style and
JAVADOC_AUTOBRIEF set to YES:

/**
* A test class. A more elaborate class description.
*/
class Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
.....................................................
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};

Similarly, to set QT_AUTOBRIEF to YES in the configuration file to take the first sentence of a Qt style
documentation block to automatically be treated as a brief description.

Documentation at other places

In above examples the comment blocks were always located in front of the declaration or definition of a
file, class or namespace or in front or after one of its members. Although this is often comfortable, there
may sometimes be reasons to put the documentation somewhere else.
Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the
body of a function or inside a normal C style comment block).

The price you pay for not putting the documentation block directly before (or after) an item is the need to
put a structural command inside the documentation block, which leads to some duplication of information.
So in practice you should avoid the use of structural commands unless other requirements force you to do
so.

Structural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer
JavaDoc style, followed by a command name and one or more parameters. The below example is for
class Test using command “\class”:

/*! \class Test

\brief A test class.

A more detailed class description.

*/

Below list shows some structural commands:

File (Header / Source) comments

\file Source code file name with extension file name.
\date Date
\author Author of this program
\version Program version
\b Change_History Date and contents of changing or modifying
Macro comments
\def To document a #define.
#define
Fucntion comment
\fn to document a function.
\param[in] Input parameter
Format: VariableName + Space + Description
\param[out
param[out]
out] Output parameter
Format: VariableName + Space + Description
\return Function return value.
Namespace comment
\namespace To document a namespace.
Class comment
\class To document a class.
Interface comment
 \interface To document an IDL interface.
Note:
Note Interfaces
Interface in C++ are implemented using Abstract Class.
Class
Enum comment
\enum To document an enumeration type.
Stuct comment
\struct To document a C-struct.
Union comment
\union To document a union.
Package comment
\package To document a Java package.
Other comment
\var To document a variable or typedef or enum value.
\brief Shore description.
\n New line
\c Convert font type.

More information about structural commands could be found in the page:

http://www.stack.nl/~dimitri/doxygen/manual/commands.html

Note:
1) To document a member of a C++ class, you must also document the class itself. The same holds for
namespaces.

2) To document a global C function, variable, typedef, enum or preprocessor definition you must first
document the file that contains it (usually this will be a header file, because that file contains the
information that is exported to other source files). Using a comment block containing a \file or @file
command to document the file in which those commands are located.

/*! \file */
or

/** @file */

3) Alternatively, you can put all members in a group (or module) using the \ingroup command and then
document the group using a comment block containing the \defgroup command. For member
functions or functions that are part of a namespace you should document either the class or
namespace.
Example – HTML output
If it succeeds to generate documents, it will have a folder named “html“ in your designated folder.

The main Web page of the generated HTML document is “index.html”.

The below figures show generated HTML documents.

(If you want to let the document include your source codes for browsing, remember to
set the variable “SOURCE_BROWSER” to YES in the doxygen configuration file.)