Doxygen Manual

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 123

DownloadDoxygen Manual
Open PDF In BrowserView PDF
Manual for version 1.3.8
Written by Dimitri van Heesch
c 1997-2004

CONTENTS

1

Contents
I

User Manual

4

1

Installation

4

2

Getting started

11

3

Documenting the code

15

4

Lists

22

5

Grouping

24

6

Including formulas

28

7

Graphs and diagrams

29

8

Preprocessing

31

9

Linking to external documentation

34

10 Frequently Asked Questions

36

11 Troubleshooting

40

II

41

Reference Manual

12 Features

42

13 Doxygen History

43

14 Doxygen usage

45

15 Doxytag usage

47

16 Doxywizard usage

48

17 Installdox usage

50

18 Automatic link generation

51

19 Configuration

54

20 Special Commands

72

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

CONTENTS

21 HTML Commands

III

Developers Manual

2

104

106

22 Doxygen’s Internals

106

23 Perl Module output format documentation

110

24 Internationalization

112

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

CONTENTS

Introduction
Doxygen is a documentation system for C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) and
to some extent PHP, C# and D.
It can help you in three ways:
1. 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, 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.
2. You can configure doxygen to extract the code structure from undocumented source files. This is very
useful to quickly find your way in large source distributions. You can also visualize the relations
between the various elements by means of include dependency graphs, inheritance diagrams, and
collaboration diagrams, which are all generated automatically.
3. You can even ‘abuse’ doxygen for creating normal documentation (as I did for this manual).
Doxygen is developed under Linux, but is set-up to be highly portable. As a result, it runs on most other
Unix flavors as well. Furthermore, executables for Windows 9x/NT and Mac OS X are available.
This manual is divided into three parts, each of which is divided into several sections.
The first part forms a user manual:
• Section Installation discusses how to download, compile and install doxygen for your platform.
• Section Getting started tells you how to generate your first piece of documentation quickly.
• Section Documenting the code demonstrates the various ways that code can be documented.
• Section Lists show various ways to create lists.
• Section Grouping shows how to group things together.
• Section Including formulas shows how to insert formulas in the documentation.
• Section Graphs and diagrams describes the diagrams and graphs that doxygen can generate.
• Section Preprocessing explains how doxygen deals with macro definitions.
• Section Linking to external documentation explains how to let doxygen create links to externally
generated documentation.
• Section Frequently Asked Questions gives answers to frequently asked questions.
• Section Troubleshooting tells you what to do when you have problems.
The second part forms a reference manual:
• Section Features presents an overview of what doxygen can do.
• Section Doxygen History shows what has changed during the development of doxygen and what still
has to be done.

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

1

CONTENTS

• Section Doxygen usage shows how to use the doxygen program.
• Section Doxytag usage shows how to use the doxytag program.
• Section Doxywizard usage shows how to use the doxywizard program.
• Section Installdox usage shows how to use the installdox script that is generated by doxygen if
you use tag files.
• Section Output Formats shows how to generate the various output formats supported by doxygen.
• Section Automatic link generation shows how to put links to files, classes, and members in the
documentation.
• Section Configuration shows how to fine-tune doxygen, so it generates the documentation you want.
• Section Special Commands shows an overview of the special commands that can be used within the
documentation.
• Section HTML Commands shows an overview of the HTML commands that can be used within the
documentation.
The third part provides information for developers:
• Section Doxygen’s Internals gives a global overview of how doxygen is internally structured.
• Section Perl Module output format documentation shows how to use the PerlMod output.
• Section Internationalization explains how to add support for new output languages.
Doxygen license
Copyright c 1997-2004 by Dimitri van Heesch.
Permission to use, copy, modify, and distribute this software and its documentation under the terms of
the GNU General Public License is hereby granted. No representations are made about the suitability of
this software for any purpose. It is provided ”as is” without express or implied warranty. See the GNU
General Public License for more details.
Documents produced by doxygen are derivative works derived from the input used in their production; they
are not affected by this license.
Projects using doxygen
I have compiled a list of projects that use doxygen (see http://www.doxygen.org/projects.html).
If you know other projects, let me know and I’ll add them.
Future work
Although doxygen is used successfully by a lot of people already, there is always room for improvement.
Therefore, I have compiled a todo/wish list (see http://www.doxygen.org/todo.html) of possible and/or requested enhancements.

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

2

CONTENTS

Acknowledgements
Thanks go to:
• Malte Zöckler and Roland Wunderling, authors of DOC++. The first version of doxygen borrowed
some code of an old version of DOC++. Although I have rewritten practically all code since then,
DOC++ has still given me a good start in writing doxygen.
• All people at Troll Tech, for creating a beautiful GUI Toolkit (which is very useful as a Windows/Unix platform abstraction layer :-)
• My brother Frank for rendering the logos.
• Harm van der Heijden for adding HTML help support.
• Wouter Slegers of Your Creative Solutions for registering the www.doxygen.org domain.
• Parker Waechter for adding the RTF output generator.
• Joerg Baumann, for adding conditional documentation blocks, PDF links, and the configuration
generator.
• Matthias Andree for providing a .spec script for building rpms from the sources.
• Tim Mensch for adding the todo command.
• Christian Hammond for redesigning the web-site.
• Ken Wong for providing the HTML tree view code.
• Petr Prikryl for coordinating the internationalisation support. All language maintainers for providing
translations into many languages.
• Gerald Steffens of E-trend for financial support.
• The band Porcupine Tree for providing hours of great music to listen to while coding.
• many, many others for suggestions, patches and bug reports.

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

3

4

Part I

User Manual
1

Installation

First go to the download page (http://www.doxygen.org/download.html)to get the latest
distribution, if you did not have it already.
This section is divided into the following sections:
• Compiling from source on Unix
• Installing the binaries on Unix
• Known compilation problems for Unix
• Compiling from source on Windows
• Installing the binaries on Windows
• Tools used to develop doxygen

1.1

Compiling from source on Unix

If you downloaded the source distribution, you need at least the following to build the executable:
• The GNU tools flex, bison and make
• In order to generate a
http://www.perl.com/).

Makefile

for

your

platform,

you

need

perl

(see

To take full advantage of doxygen’s features the following additional tools should be installed.
• Troll Tech’s GUI toolkit Qt (see http://www.trolltech.com/products/qt.html) version 2 or higher. This is needed to build the GUI front-end doxywizard.
• A LATEX distribution: for instance teTeX 1.0
par (see http://www.tug.org/interest.html#free). This is needed for generating LaTeX, Postscript, and PDF output.
• the Graph visualization toolkit version 1.8.10 or higher
par (see http://www.research.att.com/sw/tools/graphviz/). Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs. If you
compile graphviz yourself, make sure you do include freetype support (which requires the freetype
library and header files), otherwise the graphs will not render proper text labels.
• The ghostscript interpreter. To be found at www.ghostscript.com.
Compilation is now done by performing the following steps:
1. Unpack the archive, unless you already have done that:

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

1.1

Compiling from source on Unix

gunzip doxygen-$VERSION.src.tar.gz
tar xf doxygen-$VERSION.src.tar

5

# uncompress the archive
# unpack it

2. Run the configure script:
sh ./configure

The script tries to determine the platform you use, the make tool (which must be GNU make) and
the perl interpreter. It will report what it finds.
To override the auto detected platform and compiler you can run configure as follows:
configure --platform platform-type

See the PLATFORMS file for a list of possible platform options.
If you have Qt-2.1.x installed and want to build the GUI front-end, you should run the configure
script with the --with-doxywizard option:
configure --with-doxywizard

For an overview of other configuration options use
configure --help

3. Compile the program by running make:
make

The program should compile without problems and three binaries (doxygen and doxytag) should
be available in the bin directory of the distribution.
4. Optional: Generate the user manual.
make docs

To let doxygen generate the HTML documentation.
Note:
You will need the stream editor sed for this, but this should be available on any Unix platform.
The HTML directory of the distribution will now contain the html documentation (just point a HTML
browser to the file index.html in the html directory).
5. Optional: Generate a PDF version of the manual (you will need pdflatex, makeindex, and
egrep for this).
make pdf

The PDF manual doxygen manual.pdf will be located in the latex directory of the distribution.
Just view and print it via the acrobat reader.

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

1.2

Installing the binaries on Unix

1.2

Installing the binaries on Unix

After the compilation of the source code do a make install to install doxygen. If you downloaded the
binary distribution for Unix, type:
./configure
make install

Binaries are installed into the directory /bin. Use make install docs to install the
documentation and examples into /doxygen.
 defaults to /usr but can be changed with the --prefix option of the configure script. The
default  directory is /share/doc/packages and can be changed with the
--docdir option of the configure script.
Alternatively, you can also copy the binaries from the bin directory manually to some bin directory in
your search path. This is sufficient to use doxygen.
Note:
You need the GNU install tool for this to work (it is part of the fileutils package). Other install tools
may put the binaries in the wrong directory!
If you have a RPM or DEP package, then please follow the standard installation procedure that is required
for these packages.

1.3

Known compilation problems for Unix

Qt problems
The Qt include files and libraries are not a subdirectory of the directory pointed to by QTDIR on some
systems (for instance on Red Hat 6.0 includes are in /usr/include/qt and libs are in /usr/lib).
The solution: go to the root of the doxygen distribution and do:
mkdir qt
cd qt
ln -s your-qt-include-dir-here include
ln -s your-qt-lib-dir-here lib
export QTDIR=$PWD

If you have a csh-like shell you should use setenv QTDIR $PWD instead of the export command
above.
Now install doxygen as described above.
Bison problems
Versions 1.31 to 1.34 of bison contain a ”bug” that results in a compiler errors like this:
ce parse.cpp:348: member ‘class CPPValue yyalloc::yyvs’ with constructor not allowed in union
This problem has been solved in version 1.35 (versions before 1.31 will also work).
Latex problems
The file a4wide.sty is not available for all distributions. If your distribution does not have it please
select another paper type in the config file (see the PAPER TYPE tag in the config file).
HP-UX & Digital Unix problems
If you are compiling for HP-UX with aCC and you get this error:
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

6

1.3

Known compilation problems for Unix

/opt/aCC/lbin/ld: Unsatisfied symbols:
alloca (code)

then you should (according to Anke Selig) edit ce parse.cpp and replace
extern "C" {
void *alloca (unsigned int);
};

with
#include 

If that does not help, try removing ce parse.cpp and let bison rebuild it (this worked for me).
If you are compiling for Digital Unix, the same problem can be solved (according to Barnard Schmallhof)
by replacing the following in ce parse.cpp:
#else /* not GNU C. */
#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi)
#include 

with
#else /* not GNU C. */
#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi) || defined (__osf__)
#include 

Alternatively, one could fix the problem at the bison side. Here is patch for bison.simple (provided by
Andre Johansen):
--- bison.simple˜
Tue Nov 18 11:45:53 1997
+++ bison.simple
Mon Jan 26 15:10:26 1998
@@ -27,7 +27,7 @@
#ifdef __GNUC__
#define alloca __builtin_alloca
#else /* not GNU C. */
-#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi)
+#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) \
|| defined (__sparc) || defined (__sgi) || defined (__alpha)
#include 
#else /* not sparc */
#if defined (MSDOS) && !defined (__TURBOC__)

The generated scanner.cpp that comes with doxygen is build with this patch applied.
Sun compiler problems
I tried compiling doxygen only with Sun’s C++ WorkShop Compiler version 5.0 (I used ./configure
--platform solaris-cc)
Qt-2.x.y is required for this compiler (Qt-1.44 has problems with the bool type).
Compiling the doxygen binary went ok, but while linking doxytag I got a lot of link errors, like these:
QList::__vtbl
/home/dimitri/doxygen/
objects/SunWS_cache/CC_obj_6/6c3eO4IogMT2vrlGCQUQ.o
[Hint: try checking whether the first non-inlined, non-pure
virtual function of class QList is defined]

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

7

1.4

Compiling from source on Windows

These are generated because the compiler is confused about the object sharing between doxygen and
doxytag. To compile doxytag anyway do:
rm -rf objects
mkdir objects
cd src
gmake -f Makefile.doxytag

when configuring with --static I got:
Undefined
symbol
dlclose
dlsym
dlopen

first referenced
in file
/usr/lib/libc.a(nss_deffinder.o)
/usr/lib/libc.a(nss_deffinder.o)
/usr/lib/libc.a(nss_deffinder.o)

Manually adding -Bdynamic after the target rule in Makefile.doxygen and Makefile.doxytag
will fix this:
$(TARGET): $(OBJECTS) $(OBJMOC)
$(LINK) $(LFLAGS) -o $(TARGET) $(OBJECTS) $(OBJMOC) $(LIBS) -Bdynamic

GCC compiler problems
Older versions of the GNU compiler have problems with constant strings containing characters with character codes larger than 127. Therefore the compiler will fail to compile some of the translator xx.h files.
A workaround, if you are planning to use the English translation only, is to configure doxygen with the
--english-only option.
On some platforms (such as OpenBSD) using some versions of gcc with -O2 can lead to eating all memory
during the compilation of files such as config.cpp. As a workaround use –debug as a configure option or
omit the -O2 for the particular files in the Makefile.
Gcc versions before 2.95 may produce broken binaries due to bugs in these compilers.
Dot problems
Due to a change in the way image maps are generated, older versions of doxygen (<=1.2.17) will not work
correctly with newer versions of graphviz (>=1.8.8). The effect of this incompatibility is that generated
graphs in HTML are not properly clickable. For doxygen 1.3 it is recommended to use at least graphviz
1.8.10 or higher.
Red Hat 9.0 problems
If you get the following error after running make
tmake error: qtools.pro:70: Syntax error

then first type
export LANG=

before running make.

1.4

Compiling from source on Windows

Currently, I have only compiled doxygen for Windows using Microsoft’s Visual C++ (version 6.0). For
other compilers you may need to edit the perl script in wintools/make.pl a bit. Let me know what
you had to change if you got Doxygen working with another compiler.
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

8

1.4

Compiling from source on Windows

If you have Visual C++ 6.0, and the source distribution, you can easily build doxygen using the project files
in the wintools directory. If you want to build the CVS sources, or want to build from the command
line, or with another compiler, you have to follow the steps below.
Thomas Baust reported that if you have Visual Studio.NET (2003) then you should be aware that there is
a problem with the popen() and pclose() implementation, which currently leaks handles, so if you build
doxygen with it and use the INPUT FILTER, you will run to risk of crashing Windows! The problem is
reported to and confirmed by Microsoft so maybe it will fixed in the next service pack.
Since Windows comes without all the nice tools that Unix users are used to, you’ll need to install a number
of these tools before you can compile doxygen for Windows from the command-line.
Here is what is required:
• An unzip/untar tool like WinZip to unpack the tar source distribution. This can be found at
http://www.winzip.com/
The good, tested, and free alternative is the tar utility supplied with cygwin tools. Anyway,
the cygwin’s flex, bison, and sed are also recommended below.
• Microsoft Visual C++ (I only tested with version 6.0). Use the vcvars32.bat batch file to set the
environment variables (if you did not select to do this automatically during installation).
Borland C++ or MINGW (see http://www.mingw.org/) are also supported.
• Perl 5.0 or higher for Windows. This can be downloaded from: http://www.ActiveState.com/Products/ActivePerl/
• The GNU tools flex, bison, and sed. To get these working on Windows you should install the
cygwin tools (see http://sources.redhat.com/cygwin/)
Alternatively, you can also choose to download only a small subset (see
http://www.doxygen.org/dl/cygwin tools.zip)of the cygwin tools that I put
together just to compile doxygen.
As a third alternative one could use the GNUWin32 tools that can be found at
http://gnuwin32.sourceforge.net/
Make sure the BISON SIMPLE environment variable points to the location where the files
bison.simple and is located. For instance if these file is in c:\tools\cygwin\usr\share
then BISON SIMPLE should be set to c:/tools/cygwin/usr/share/bison.simple
Also make sure the tools are available from a dos box, by adding the directory they are in to the
search path.
For those of you who are very new to cygwin (if you are going to install it from scratch), you
should notice that there is an archive file bootstrap.zip which also contains the tar utility
(tar.exe), gzip utilities, and the cygwin1.dll core. This also means that you have the tar
in hands from the start. It can be used to unpack the tar source distribution instead of using WinZip
– as mentioned at the beginning of this list of steps.
• From Doxygen-1.2.2-20001015 onwards, the distribution includes the part of Qt-2.x.y that is needed
for to compile doxygen and doxytag, The Windows specific part were also created. As a result
doxygen can be compiled on systems without X11 or the commerical version of Qt.
For doxywizard, a complete Qt library is still a requirement however. You can download the noncommercial version from Troll-Tech web-site. See doxygen download page for a link.
• To generate LaTeX documentation or formulas in HTML you need the tools: latex,
dvips and gswin32.
To get these working under Windows install the fpTeX distribution.
You can find more info at: http://www.fptex.org/ and download it
from CTAN or one of its mirrors.
In the Netherlands for example this would be:
ftp://ftp.easynet.nl/mirror/CTAN/systems/win32/fptex/
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

9

1.4

Compiling from source on Windows

10

Make sure the tools are available from a dos box, by adding the directory they are in to the search
path.
For your information, the LaTeX is freely available set of so called macros and styles on the top
of the famous TeX program (by famous Donald Knuth) and the accompanied utilities (all available
for free). It is used for high quality typesetting. The result – in the form of so called DVI (DeVice
Independent) file – can be printed or displayed on various devices preserving exactly the same look
up to the capability of the device. The dvips allows you to convert the dvi to the high quality
PostScript (i.e. PostScript that can be processed by utilities like psnup, psbook, psselect, and
others). The derived version of TeX (the pdfTeX) can be used to produce PDF output instead of DVI,
or the PDF can be produced from PostScript using the utility ps2pdf.
If you want to use MikTeX then you need to select at least the medium size
installation.
For really old versions of MikTex or minimal installations, you
may need to download the fancyhdr package separately.
You can find it at:
ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/supported/fancyhdr/

• If you want to generate compressed HTML help (see GENERATE HTMLHELP) in the
config file, then you need the Microsoft HTML help workshop. You can download it at:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vs
HH1Start.asp
• If you used WinZip to extract the tar archive it will (apparently) not create empty folders, so you
have to add the folders objects and bin manually in the root of the distribution before compiling.
• the Graph visualization toolkit version 1.8.10
(see http://www.research.att.com/sw/tools/graphviz/). Needed for the include
dependency graphs, the graphical inheritance graphs, and the collaboration graphs.
Compilation is now done by performing the following steps:
1. Open a dos box. Make sure all tools (i.e. nmake, latex, gswin32, dvips, sed, flex, bison,
cl, rm, and perl), are accessible from the command-line (add them to the PATH environment
variable if needed).
Notice: The use of LaTeX is optional and only needed for compilation of the documentation into
PostScript or PDF. It is not needed for compiling the doxygen’s binaries.
2. Go to the doxygen root dir and type:
make.bat msvc

This should build the executables doxygen.exe and doxytag.exe using Microsoft’s Visual
C++ compiler (The compiler should not produce any serious warnings or errors).
You can use also the bcc argument to build executables using the Borland C++ compiler, or mingw
argument to compile using GNU gcc.
3. To build the examples, go to the examples subdirectory and type:
nmake

4. To generate the doxygen documentation, go to the doc subdirectory and type:
nmake

The generated HTML docs are located in the ..\html subdirectory.
The sources for LaTeX documentation are located in the ..\latex subdirectory. From those
sources, the DVI, PostScript, and PDF documentation can be generated.

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

1.5

1.5

Installing the binaries on Windows

Installing the binaries on Windows

There is no fancy installation procedure at the moment (if anyone can add it in a location independent way
please let me know).
To install doxygen, just copy the binaries from the bin directory to a location somewhere in the path.
Alternatively, you can include the bin directory of the distribution to the path.

1.6

Tools used to develop doxygen

Doxygen was developed and tested under Linux using the following open-source tools:
• GCC version 2.95.3
• GNU flex version 2.5.4
• GNU bison version 1.35
• GNU make version 3.79.1
• Perl version 5.005 03
• VIM version 5.8
• Mozilla 1.0
• Troll Tech’s tmake version 1.3 (included in the distribution)
• teTeX version 1.0
• CVS 1.10.7

2

Getting started

The executable doxygen is the main program that parses the sources and generates the documentation.
See section Doxygen usage for more detailed usage information.
The executable doxytag is only needed if you want to generate references to external documentation
(i.e. documentation that was generated by doxygen) for which you do not have the sources. See section
Doxytag usage for more detailed usage information.
Optionally, the executable doxywizard can be used, which is a graphical front-end for editing the configuration file that is used by doxygen.
The following figure shows the relation between the tools and the flow of information between them:

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

11

2.1

Step 1: Creating a configuration file

12

Doxywizard

Your application
XML files

generate/edit

read

custom
output

doxmlparser lib

Config file
Doxyfile
make ps
read

generate/update

Latex files
+
Makefile

postscript
latex

make pdf

PDF

read
Sources

Doxygen
read
read

generate
Man pages

Custom
− headers
− footers

Tag file(s)

− images

Windows only

refman.rtf

import

MS−Word

doc

generate

HTML
pages

Doxytag

read

chm
HTML Help Workshop

parse

Figure 1: Doxygen information flow

2.1

Step 1: Creating a configuration file

Doxygen uses a configuration file to determine all of its settings. Each project should get its own configuration file. A project can consist of a single source file, but can also be an entire source tree that is recursively
scanned.
To simplify the creation of a configuration file, doxygen can create a template configuration file for you.
To do this call doxygen from the command line with the -g option:
doxygen -g 

where  is the name of the configuration file. If you omit the file name, a file named
Doxyfile will be created. If a file with the name  already exists, doxygen will rename
it to .bak before generating the configuration template. If you use - (i.e. the minus sign) as
the file name then doxygen will try to read the configuration file from standard input (stdin).
The configuration file has a format that is similar to that of a (simple) Makefile. It contains of a number of
assignments (tags) of the form:
TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

2.2

Step 2: Running doxygen

You can probably leave the values of most tags in a generated template configuration file to their default
value. See section Configuration for more details about the configuration file.
If you do not wish to edit the config file with a text editor, you should have a look at doxywizard, which is a
GUI front-end that can create, read and write doxygen configuration files, and allows setting configuration
options by entering them via dialogs.
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 put the root directory or
directories after 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. To further fine-tune the list of files that is parsed the EXCLUDE and EXCLUDE PATTERNS tags
can be used. To omit all test directories from a source tree for instance, one could use:
EXCLUDE_PATTERNS = */test/*

Doxygen normally parses files if they are C or C++ sources. If a file has a .idl or .odl extension it is
treated as an IDL file. If it has a .java extension it is treated as a file written in Java. Files ending with
.cs are treated as C# files. Finally, files with the extensions .php, .php4, .inc or .phtml are treated
as PHP sources.
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 documented result would be. 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.
To analyse 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).

2.2

Step 2: Running doxygen

To generate the documentation you can now enter:
doxygen 

Doxygen will create a html, rtf, latex and/or man directory inside the output directory. As the names
suggest these directories contain the generated documentation in HTML, RTF, LATEX and Unix-Man page
format.
The default output directory is the directory in which doxygen is started. The directory to which the
output is written can be changed using the OUTPUT DIRECTORY, HTML OUTPUT, RTF OUTPUT,
LATEX OUTPUT, and MAN OUTPUT tags of the configuration file. If the output directory does not
exist, doxygen will try to create it for you.
The generated HTML documentation can be viewed by pointing a HTML browser to the index.html
file in the html directory. For the best results a browser that supports cascading style sheets (CSS) should
be used (I’m currently using Netscape 4.61 to test the generated output).
The generated LATEX documentation must first be compiled by a LATEX compiler (I use teTeX distribution
version 0.9 that contains TEX version 3.14159). To simplify the process of compiling the generated documentation, doxygen writes a Makefile into the latex directory. By typing make in the latex
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

13

2.3

Step 3: Documenting the sources

directory the dvi file refman.dvi will be generated (provided that you have a make tool called make of
course). This file can then be viewed using xdvi or converted into a PostScript file refman.ps by typing
make ps (this requires dvips). To put 2 pages on one physical page use make ps 2on1 instead. The
resulting PostScript file can be send to a PostScript printer. If you do not have a PostScript printer, you can
try to use ghostscript to convert PostScript into something your printer understands. Conversion to PDF is
also possible if you have installed the ghostscript interpreter; just type make pdf (or make pdf 2on1).
To get the best results for PDF output you should set the PDF HYPERLINKS tag to YES.
The generated man pages can be viewed using the man program. You do need to make sure the man
directory is in the man path (see the MANPATH environment variable). Note that there are some limitations
to the capabilities of the man page format, so some information (like class diagrams, cross references and
formulas) will be lost.

2.3

Step 3: Documenting the sources

Although documenting the source is presented as step 3, in a new project this should of course be step 1.
Here I assume you already have some code and you want doxygen to generate a nice document describing
the API and maybe the internals as well.
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, classes and namespaces. So how do you document
these? For members, classes and namespaces there are basically two options:
1. Place a special documentation block in front of the declaration or definition of the member, class
or namespace. For file, class and namespace members it is also allowed to place the documention
directly after the member. See section Special documentation blocks to learn more about special
documentation blocks.
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, class, namespace or file). See section
Documentation at other places to learn more about structural commands.
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, variable, typedefs, defines) do not need an explicit
structural command; just putting a special documentation block in front or behind them will do.
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:
• The special commands inside the documentation are executed. See section Special Commands for
an overview of all commands.
• If a line starts with some whitespace followed by one or more asterisks (∗) and then optionally more
whitespace, then all whitespace and asterisks are removed.
• All resulting blank lines are treated as a paragraph separators. This saves you from placing newparagraph commands yourself in order to make the generated documentation readable.
• Links are created for words corresponding to documented classes.
• Links to members are created when certain patterns are found in the text. See section Automatic link
generation for more information on how the automatic link generation works.
• HTML tags that are in the documentation are interpreted and converted to LATEX equivalents for the
LATEX output. See section HTML Commands for an overview of all supported HTML tags.
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

14

15

3

Documenting the code

3.1

Special documentation blocks

A special documentation block is a C or C++ 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 types of descriptions, which together form the documentation: a brief
description and detailed description, both are optional. Having more than one brief or detailed description
however, is not allowed.
As the name suggest, a brief description is a short one-liner, whereas the detailed description provides
longer, more detailed documentation.
There are several ways to mark a comment block as a detailed description:
1. You can use the JavaDoc style, which consist of a C-style comment block starting with two ∗’s, like
this:
/**
* ... text ...
*/

2. or you can use the Qt style and add an exclamation mark (!) after the opening of a C-style comment
block, as shown in this example:
/*!
* ... text ...
*/

In both cases the intermediate ∗’s are optional, so
/*!
... text ...
*/

is also valid.
3. A third alternative is to use a block of at least two C++ comment lines, where each line starts with
an additional slash or an exclamation mark. Here are examples of the two cases:
///
/// ... text ...
///

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

4. Some people like to make their comment blocks more visible in the documentation. For this purpose
you can use the following:
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

3.1

Special documentation blocks

For the brief description there are also several posibilities:
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.
Here is an example:
/*! \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. Here is an example:
/** 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. A third option is to use a special C++ style comment which does not span more than one line. Here
are two examples:
/// 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.
As you can see doxygen is quite flexible. The following however is not legal
//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Oops, another detailed description!
*/

because doxygen only allows one brief and one 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.
Here is an example of a documented piece of C++ code using the Qt style:

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

16

3.1

Special documentation blocks

17

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

*/
TVal1. */
TVal2. */
TVal3. */

//! A constructor.
/*!
A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
˜Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa Test(), ˜Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! 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
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

3.1

Special documentation blocks

detailed description.
The brief descriptions are included in the member overview of a 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
config 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 behaviour 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. Here is an 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,
TVal2,
TVal3
}
*enumPtr,
enumVar;

/**< enum value TVal1. */
/**< enum value TVal2. */
/**< enum value TVal3. */
/**< enum pointer. Details. */
/**< enum variable. Details. */

/**
* A constructor.
* A more elaborate description of the constructor.
*/
Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
˜Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ˜Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

18

3.2

Putting documentation after members

/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};

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. As a compromise the brief description could be placed
before the declaration and the detailed description before the member definition.

3.2

Putting documentation after members

If you want to document the members of a file, struct, union, class, or enum, and you want to put the
documentation for these members inside the compound, it is sometimes desired to place the documentation
block after the member instead of before. For this purpose you should put an additional < marker in the
comment block.
Here are some examples:
int var; /*!< Detailed description after the member */

This block can be used to put a Qt style detailed documentation block after a member. Other ways to do
the same are:
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

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

19

3.3

Documentation at other places

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

Note that these blocks have the same structure and meaning as the special comment blocks in the previous
section only the < indicates that the member is located in front of the block instead of after the block.
Here is an example of the use of these comment blocks:
/*! A test class */
class Test
{
public:
/** An enum type.
* The documentation
*/
enum EnumType
{
int EVal1,
/**<
int EVal2
/**<
};
void member();
//!<
protected:
int value;

block cannot be put after the enum!

enum value 1 */
enum value 2 */
a member function.

/*!< an integer value */

};

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 mentioned in the next section (like \class) are ignored inside these comment
blocks.

3.3

Documentation at other places

So far we have assumed that the documentation blocks are 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. For documenting
a file this is even required since there is no such thing as ”in front of a file”. 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 before (or after) an item is the need to put a
structural command inside the documentation block, which leads to some duplication of information.
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. For instance, if you want to
document the class Test in the example above, you could have also put the following documentation
block somewhere in the input that is read by doxygen:
/*! \class Test
\brief A test class.
A more detailed class description.
*/

Here the special command \class is used to indicate that the comment block contains documentation for
the class Test. Other structural commands are:
User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

20

3.3

Documentation at other places

• \struct to document a C-struct.
• \union to document a union.
• \enum to document an enumeration type.
• \fn to document a function.
• \var to document a variable or typedef or enum value.
• \def to document a #define.
• \file to document a file.
• \namespace to document a namespace.
• \package to document a Java package.
• \interface to document an IDL interface.
See section Special Commands for detailed information about these and many other commands.
To document a member of a C++ class, you must also document the class itself. The same holds for
namespaces. To document a global C function, 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).
Let’s repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum,
macros, etc), you must document the file in which they are defined. In other words, there must at least be a
/*! \file */

or a
/** @file */

line in this file.
Here is an example of a C header named structcmd.h that is documented using structural commands:
/*! \file structcmd.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

21

22

*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
\param fd The descriptor to write to.
\param buf The data buffer to write.
\param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

Because each comment block in the example above contains a structural command, all the comment blocks
could be moved to another location or input file (the source file for instance), without affecting the generated
documentation. The disadvantage of this approach is that prototypes are duplicated, so all changes have
to be made twice! Because of this you should first consider if this is really needed, and avoid structural
commands if possible. I often receive examples that contain \fn command in comment blocks which are
place in front of a function. This is clearly a case where the \fn command is redundant and will only lead
to problems.

4

Lists

Doxygen has a number of ways to create lists of items.
Using dashes
By putting a number of column-aligned minus signs at the start of a line, a bullet list will automatically be
generated. Numbered lists can also be generated by using a minus followed by a hash. Nesting of lists is
allowed.
Here is an example:
/*!
* A list of
*
- mouse
*
-#
*
-#
*

events:
events
mouse move event
mouse click event\n
More info about the click event.

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

23

*
-# mouse double click event
*
- keyboard events
*
-# key down event
*
-# key up event
*
* More text here.
*/

The result will be:
A list of events:
• mouse events
1. mouse move event
2. mouse click event
More info about the click event.
3. mouse double click event
• keyboard events
1. key down event
2. key up event
More text here.
If you use tabs within lists, please make sure that TAB SIZE in the configuration file is set to the correct
tab size.
You can end a list by starting a new paragraph or by putting a dot (.) on an empty line at the same indent
level as the list you would like to end.
Here is an example that speaks for itself:
/**
* Text before the list
* - list item 1
*
- sub item 1
*
- sub sub item 1
*
- sub sub item 2
*
.
*
The dot above ends the sub sub item list.
*
More text for the first sub item
*
.
*
The dot above ends the first sub item.
*
More text for the first list item
*
- sub item 2
*
- sub item 3
* - list item 2
* .
* More text in the same paragraph.
*
* More text in a new paragraph.
*/

Using HTML commands
If you like you can also use HTML commands inside the documentation blocks. Using these commands
has the advantage that it is more natural for list items that consists of multiple paragraphs.
Here is the above example with HTML commands:

User Manual for Doxygen 1.3.8, written by Dimitri van Heesch c 1997-2004

24

/*!
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*/

A list of events:
  • mouse events
    1. mouse move event
    2. mouse click event\n More info about the click event.
    3. mouse double click event
  • keyboard events
    1. key down event
    2. key up event
More text here. Note: The indentation here is not important. Using \arg or @li For compatibility with the Troll Tech’s internal documentation tool and with KDoc, doxygen has two commands that can be used to create simple unnested lists. See \arg and \li for more info. 5 Grouping Doxygen has two mechanisms to group things together. One mechanism works at a global level, creating a new page for each group. These groups are called ”modules” in the documentation. The other mechanism works within a member list of some compound entity, and is refered to as a ”member group”. 5.1 Modules Modules are a way to group things together on a separate page. You can document a group as a whole, as well as all individual members. Members of a group can be files, namespaces, classes, functions, variables, enums, typedefs, and defines, but also other groups. To define a group, you should put the \defgroup command in a special comment block. The first argument of the command is a label that should uniquely identify the group. You can make an entity a member of a specific group by putting a \ingroup command inside its documentation block. The second argument is the title of the group. To avoid putting \ingroup commands in the documentation of each member you can also group members together by the open marker @{ before the group and the closing marker @} after the group. The markers can be put in the documentation of the group definition or in a separate documentation block. Groups can also be nested using these grouping markers. You will get an error message when you use the same group label more than once. If you don’t want doxygen to enforce unique labels, then you can use \addtogroup instead of \defgroup. It can be used exactly like \defgroup, but when the group has been defined already, then it silently merges the existing documentation with the new one. The title of the group is optional for this command, so you can use /** \addtogroup

Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Page Count                      : 123
Page Mode                       : UseOutlines
Author                          : 
Title                           : 
Subject                         : 
Creator                         : LaTeX with hyperref package
Producer                        : pdfTeX-1.10b
Create Date                     : 2004:07:21 18:41:00
EXIF Metadata provided by EXIF.tools

Navigation menu