Doxygen Manual
User Manual:
Open the PDF directly: View PDF .
Page Count: 123
Download | |
Open PDF In Browser | View 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: 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
- mouse events
- mouse move event
- mouse click event\n More info about the click event.
- mouse double click event
- keyboard events
- key down event
- key up event
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:00EXIF Metadata provided by EXIF.tools