Manual for version 1.3.2 Written by Dimitri van Heesch c 1997-2003 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 39 II Reference Manual 41 12 Features 41 13 Doxygen History 43 14 Doxygen usage 45 15 Doxytag usage 46 16 Doxysearch usage 48 17 Doxywizard usage 50 18 Installdox usage 51 19 Automatic link generation 52 20 Configuration 55 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 CONTENTS 2 21 Special Commands 72 22 HTML Commands 101 III Developers Manual 104 23 Doxygen’s Internals 104 24 Perl Module output format documentation 108 25 Internationalization 110 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 CONTENTS Introduction Doxygen is a documentation system for C++, C, Java, IDL (Corba and Microsoft flavors) and to some extent PHP and C#. It can help you in three ways:.: • 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. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 1 CONTENTS • Section Doxygen usage shows how to use the doxygen program. • Section Doxytag usage shows how to use the doxytag program. • Section Doxysearch usage shows how to use the doxysearch 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.-2003 by Dimitri van Heesch.. Projects using doxygen I have compiled a list of projects that use doxygen (see). 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) of possible and/or requested enhancements. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 2 CONTENTS Petr Prikryl for coordinating the internationalisation support. All language maintainers for providing translations into many languages. • Erik Jan Lingen of Habanera, Mark Roddy, Paul Schwartz, Charles Duffy, Vadym Voznyuk, Philip Walton, Dwight Browne, Andreas Fredriksson, Karel Lindveld, Ivan Lee, Albert Vernon, Adam McKee, Vijapurapu Anatharac, Ben Hunsberger and Walter Wartenweiler, Jeff Garbers, David Harris, Terry Brown and Nicolas Reimen for donating money. • The Comms group of Symbian for donating an ultra cool Revo plus organizer! • Steve Upstill of Weta Digital for sending me some Lord of the Rings goodies. • The band Porcupine Tree for providing hours of great music to listen to while coding. • many, many others for suggestions, patches and bug reports. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003.3.2, written by Dimitri van Heesch 1997-2003, doxytag, and doxy.3.2, written by Dimitri van Heesch 1997-2003 file.3.2, written by Dimitri van Heesch 1997-2003.y] c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 7 1.4 Compiling from source on Windows. 1.4: • An unzip/untar tool like WinZip to unpack the tar source distribution. This can be found at 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. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 8 1.4 Compiling from source on Windows • 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) are also supported. • Perl 5.0 or higher for Windows. This can be downloaded from: • The GNU tools flex, bison, and sed. To get these working on Windows you should install the cygwin tools (see) Alternatively, you can also choose to download only a small subset (see 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 Make sure the BISONLIB environment variable points to the location where the files bison.simple and bison.hairy are located. For instance if these files are in c:\tools\cygwin\share then BISONLIB should be set to //c/tools/cygwin/share/. • From Doxygen-1.2.2-20001015 onwards, the distribution includes the part of Qt-2.x.y that is needed for to compile doxygen, doxytag, and doxysearch. 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: and download it from CTAN or one of its mirrors. In the Netherlands for example this would be: 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: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 9 1.5 Installing the binaries on Windows • 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: • 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). 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.. 2. Go to the doxygen root dir and type:. 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. 1.5 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. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 10 1.6 1.6 Tools used to develop doxygen 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 or to create a search index for the search engine. See section Doxytag usage for more detailed usage information. The executable doxysearch is only needed if you want to use the search engine. See section Doxysearch usage for more detailed usage information. Optionally, the executable doxywizard is a GUI front-end for editing the configuration files that are used by doxygen. The following figure shows the relation between the tools and the flow of information between them: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 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 Latex files + Makefile generate/update postscript latex make pdf PDF read Sources Doxygen read read generate Man pages Custom − headers − footers Tag file(s) − images Windows only refman.rtf search index import MS−Word doc generate generate uses HTML pages Doxytag read chm HTML Help Workshop parse Doxysearch used from generates Figure 1: Doxygen information flow 2.1 Step 1: Creating a configuration file). 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 ... c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 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 like 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). 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. analyse). 2.2 Step 2: Running doxygen To generate the documentation you can now enter: doxygen <config-file> 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 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 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). tag to YES.. 2.3 Step 3: Documenting the sources Although documenting the source. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 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. //! //!... text ... //! 4. Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following: ///////////////////////////////////////////////// /// ... text ... ///////////////////////////////////////////////// c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 3.1 Special documentation blocks: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 16 3.1 Special documentation blocks 17 //! c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 3.1 Special documentation blocks. */ ˜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); c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 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); };. 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. //!< 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 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 19 3.3 Documentation at other places before (or after) an item is the need to put a structural command inside the documentation block, which leads to some duplication of information.: /*! \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: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 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: /*! ! c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 21 22 */ /*! . 4 Lists Doxygen has. Here is an example: /*! * A list of * - mouse * -# * -# * events: events mouse move event mouse click event\n More info about the click event. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 23 * -# within lists, please make sure that TAB SIZE in the configuration file is set to the correct tab size. consists of multiple paragraphs. Here is the above example with HTML commands: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 24 /*! * * * * * * * * * * * * * * * * */ A list of events: <ul> <li> mouse events <ol> <li>mouse move event <li>mouse click event\n More info about the click event. <li>mouse double click event </ol> <li> keyboard events <ol> <li>key down event <li>key up event </ol> </ul> 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”.> */ c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 5.1 Modules /*\@{*/ /*\@}*/ to add members to a group that is defined in more detail elsewhere.. Example: /** @defgroup group1 The First Group * This is the first group * @{ */ /** @brief class C1 in group 1 */ class C1 {}; /** @brief class C2 in group 1 */ class C2 {}; /** function in group 1 */ c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 25 5.1 Modules [email protected] */ class C5 {}; /** @ingroup group1 group2 group3 group4 * namespace N1 is in four groups * @sa @link group1 The first [email protected],. * @{ */ c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 26 5.2 Member Groups /** physcially inside the member group’s body.. Example: /** A class. Details */ class Test { public: //@{ /** Same documentation for both members. Details */ void func1InGroup1(); void func2InGroup1(); //@} /** Function without group. Details. */ void ungroupedFunction(); void func1InGroup2(); c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 27 28). 0.9 distribution. • dvips: a tool to convert DVI files to PostScript files I have used version 5.86 from Radical Eye software for testing. • gs: the GhostScript interpreter for converting PostScript files to bitmaps. I have used Aladdin GhostScript 5.10 for testing. There are two . c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 29 2. Unnumbered displayed formulas that are centered on a separate line. These formulas should be put between \f[ and \f] commands. An c(ξ)ut (ξ, t) dξ dt |I2 | = ψ(t) u(a, t) − 0 γ(t) k(θ, t) a Formulas should be valid commands in LATEX’s math-mode. Warning: Currently, doxygen is not very fault tolerant in recovering from typos in formulas. It may have to be necessary to remove the file formula.repository that is written from AT&T and Lucent Bell Labs and can be found at If you have the ”dot” tool available in the path, you can set HAVE DOT to YES in the configuration file to let doxygen use it. Doxygen uses the ”dot” tool to generate the following graphs: • if GRAPHICAL HIERARCHY is set to YES, a graphical representation of the class hierarchy will be drawn, along with the textual one. Currently this feature is supported for HTML only. Warning: When you have a very large class hierarchy where many classes derive from a common base class, the resulting image may become too big to handle for some browsers.). c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 30 The elements in the class diagrams in HTML and RTF have the following meaning: •. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 31:: or you can use installdox to set the links as follows: installdox [email protected]:: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 38). 13. Help! I get the cryptic message ”input buffer overflow, can’t enlarge buffer because scanner uses REJECT” This error happens when doxygen lexical scanner has a rule that matches more than 16K of input characters in one go. I’ve seen this happening on a very large generated file (>16K lines), where the built-in preprocessor converted it into an empty file (with >16K of newlines). Another case where this might happen is if you have lines in your code with more than 16. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 39, so it does not know that class A relates to class B in the following example #include <vector> using namespace std; class B {}; class A { public: vector<B> m_bvec; }; To overcome this problem you could provide the definition of the vector class to doxygen (by including the file that defines it at the INPUT tag in the config file). Since STL header files are often messy, a (possibly) better approach is to include a dummy definition of a vector class to the input. Here is an example of a dummy STL file for the vector class: namespace std { template<class T> class vector { public: T element; }; } I’m still looking for someone who can provide me with definitions for all (relevant) STL classes. 16.”). 17.... 11 Troubleshooting Known problems: • Doxygen is not a real compiler, it is only a lexical scanner. This means that it can and will not detect errors in your source code. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 40 • Since everthing can be properly linked to the corresponding documentation, because of possible ambiguities or lack of information about the context in which the code fragment is found. • It is not possible to insert a non-member function f in a class A using the \relates.3.2, written by Dimitri van Heesch 1997-2003 41 How to report a bug If you find a bug please send an e-mail to: [email protected]: attachment for easier processing. If you have ideas (or even better some code or a patch) how to fix existing bugs and limitations please discuss them on the developers mailing list. Patches can also send directly to [email protected] For patches please use ”diff -uN” or include the files you modified. If you send more than one file please tar or zip everything, so I only have to save and download one file. Note that you can also post bug reports via the bug tracker at sourceforge, but I do not really like this because of its web interface, which I find rather clumpsy to use. Part II Reference Manual 12 Features • Requires very little overhead from the writer of the documentation. Plain text will do, but for more fancy or structured output HTML tags and/or some of doxygen’s special commands can be used. • Supports C/C++, Java, (Corba and Microsoft) Java, IDL, and to some extent C# and PHP sources. • Supports documentation of files, namespaces, classes, structs, unions, templates, variables, functions, typedefs, enums and defines. • JavaDoc (1.1), Qt-Doc, and KDOC compatible. • Automatically generates class diagrams in HTML (as clickable image maps) and LATEX (as Encapsulated PostScript images). • Uses the dot tool of the Graphviz tool kit to generate include dependency graphs, collaboration diagrams, and graphical class hierarchy graphs. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 42 • Allows you to put documentation in the header file (before the declaration of an entity), source file (before the definition of an entity) or in a separate file. • Can generate. Although doxygen can be used in any C or C++ project,! c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 43. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 44 search engine doxysearch, that allows you to search through the generated documentation. • A configuration file instead of command-line options. A default configuration file can be generated by doxygen. • Added an option to generate output for undocumented classes. • Added an option to generate output for private members.. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 45.: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 46. If you also want to use the search engine, you should look at section Doxysearch usage. 15 Doxytag usage Doxytag is a small command line based utility. It has two functions: • Doxytag. • Doxytag can generate a search index for the documentation generated with doxygen or for the Qt documentation. See the documentation of doxysearch for more information on how to do this. A search index contains information about all the words (and all substrings thereof) that are contained in the documentation. For each string the index contains the set of documentation blocks that contain the string and the frequency of occurrence. This way doxysearch can search for words very quickly (most queries are processed within a few milliseconds on my system.) In both cases the input of doxytag consists of a set of HTML files. Important: If you use tag files or use a search engine,. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 47: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 48 doxytag -t qt.tag $QTDIR/doc/html A typical example to use doxytag to generate a search index is: doxytag -s search.idx Note: In the current version of doxygen, the search index must be called search.idx. 16 Doxysearch usage Doxysearch is a small, fast and highly portable search engine that allows you to search for strings or words in the documentation generated by doxygen or in the Qt documentation (see below). Doxysearch must be run as a CGI binary. This implies the following: • There must be a HTTP daemon running on the system where you want to install the documentation (the target) • You must have permission to install and execute a CGI binary on the target. Ask your system administrator or provider if you are unsure if this is possible. Generating the search engine To include a search engine in the documentation generated by doxygen follow these steps: 1. Generate a configuration file with doxygen using the -g option, if you haven’t done this already. 2. Edit the search engine section (see section Search engine options of the configuration file). Make sure the SEARCHENGINE tag is set to YES and that all paths are correct. 3. Use doxygen to generate the documentation. Apart from the documentation, Doxygen will create the following files: • A small shell script. The name of the script is determined by the CGI NAME tag in the configuration file. The script is a small wrapper that calls doxysearch with the correct parameters. Using this script allows multiple search engines for different projects to be present in one directory. •. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 49 • search.gif: this is the image that is used for the search button. Note: On the Windows platform Unix shell scripts cannot be used. In fact the HTTP daemon that I tried (apache for Windows) only recognized .cgi files that were renamed executables (so DOS batch files do not seem to work either). Therefore, on Windows a small C program will be generated by doxygen. You should compile and link the program with your favourite compiler and change the extension of the executable from .exe to .cgi. 4. Copy (or move) the CGI script to the directory where the CGI binaries are located. This is usually a special directory on your system or in your home directory. Consult the manual of your HTTP daemon or your system administrator to find out where this directory resides on your system. 5. Go to the directory where the generated HTML files are located and run doxytag as follows: doxytag -s search.idx This will create a search index with the name search.idx. Currently the index file must be called like this. 6. If you change the location of the search engine or the documentation and you do not want to regenerate the HTML output, you can simply edit the generated search.cfg file and run the generated installdox script to correct the links in the documentation. Creating a search engine to search in the Qt documentation Using doxytag and doxysearch it is possible to create a search engine for the Qt documentation, without needing the sources! This can be done by carefully following these steps: 1. Go to the html directory of the Qt-distribution: cd $QTDIR/html 2. Generate the search index by typing: doxytag -s search.idx in the directory where the HTML files are located. This will parse all files and build a search index. Apart from the file search.idx two other files will be generated: search.gif and search.cgi Note: Doxytag requires quite a large amount of memory to generate the search index (about 30 MB on my Linux box)! The resulting index file requires about 3 MB of space on your disk. 3. Edit the shell script search.cgi with c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 50 4. CGI binaries are usually located in a special directory. Consult the manual of your HTTP daemon or your system administrator to find out, where this directory resides on your system. Copy (or move) the search.cgi script to this directory. If needed you may change the name of the script. On my system, this becomes: cp search.cgi /usr/local/lib/httpd/cgi-bin/ 5. Create a text-file with the name: 6. Add a link to the search engine in the Qt documentation. On my system, I have put a line <li><a href="">Search the documentation<a> in the additional information section of the index.html file. 7. Start your favourite web browser and click on the link. If everything is OK, you should get a page where you can enter search terms. 17 Doxywizard usage Doxywizard is a GUI front-end for creating and editing configuration files that are used by doxygen. Doxywizard consists of a single executable that, when started, pops up a window. The main window has a number of tab field, button with a circular ”refresh” arrow that, when pressed, replaces the selected item in the list with the string entered in the edit field. • For file and folder entries, there are special buttons that start a file dialog. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 51 18. 18.1 Output Formats. Note that the XML output is still under development. The following output formats are indirectly supported by doxygen: Compressed HTML (a.k.a. Windows 98 help) Generated by Microsoft’s HTML Help workshop from the HTML output if GENERATE HTMLHELP is set to YES. PostScript Generated from the LATEX output by running make ps in the output directory. For the best results PDF HYPERLINKS should be set to NO. PDF Generated from the LATEX output by running make pdf in the output directory. In order to get hyperlinks in the PDF file, PDF HYPERLINKS should be set to YES in the configuration file. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 52 19 Automatic link generation Most LATEX. 19.1 Links to web pages and mail addresses Doxygen will automatically replace any URLs and mail addresses found in the documentation by links (in HTML). 19.2 Links to classes. All words in the documentation that correspond to a documented class will automatically be replaced by a link to the page containing the documentation of the class. If you want to prevent that a word that corresponds to a documented class is replaced by a link you should put a % in front of the word. 19.3 Links to files. All words that contain a dot (.) that is not the last character in the word are considered to be file names. If the word is indeed the name of a documented input file, a link will automatically be created to the documentation of that file. 19.4 Links to functions. Links to functions are created if one of the following patterns is encountered: 1. <functionName>"("<argument-list>")" 2. <functionName>"()" 3. "::"<functionName> 4. (<className>"::")n <functionName>"("<argument-list>")" 5. (<className>"::")n <functionName>"()" 6. (<className>"::")n <functionName> where n>0. Note 1: The patterns above should not contain spaces, tabs or newlines. Note 2: For JavaDoc compatibility a # may be used instead of a :: in the patterns above. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 19.5 Links to variables, typedefs, enum types, enum values and defines. Note 3: In the documentation of a class containing a member foo, a reference to a global variable is made using ::foo, whereas #foo will link to the member. For non overloaded members the argument list may be omitted. If a function is overloaded and no matching argument list is specified (i.e. pattern 2 or 5 is used), a link will be created to the documentation of one of the overloaded members. For member functions the class scope (as used in patterns 4 to 6) may be omitted, if: 1. The pattern points to a documented member that belongs to the same class as the documentation block that contains the pattern. 2. The class that corresponds to the documentation blocks that contains the pattern has a base class that contains a documented member that matches the pattern. 19.5 Links to variables, typedefs, enum types, enum values and defines. All of these entities can be linked to in the same way as described in the previous section. For sake of clarity it is advised to only use patterns 3 and 6 in this case. Example: /*! \file autolink.cpp Testing automatic link generation. A link to a member of the Test class: Test::member, More specific links to the each of the overloaded members: Test::member(int) and Test#member(int,int) A link to a protected member variable of Test: Test#var, A link to the global enumeration type #GlobEnum. A link to the define #ABS(x). A link to the destructor of the Test class: Test::˜Test, A link to the typedef ::B. A link to the enumeration type Test::EType A link to some enumeration values Test::Val1 and ::GVal2 */ /*! Since this documentation block belongs to the class Test no link to Test is generated. Two ways to link to a constructor are: #Test and Test(). Links to the destructor are: #˜Test and ˜Test(). A link to a member in this class: member(). More specific links to the each of the overloaded members: member(int) and member(int,int). A link to the variable #var. A link to the global typedef ::B. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 53 19.6 typedefs. 54 A link to the global enumeration type #GlobEnum. A link to the define ABS(x). A link to a variable \link #var using another text\endlink as a link. A link to the enumeration type #EType. A link to some enumeration values: \link Test::Val1 Val1 \endlink and ::GVal1. And last but not least a link to a file: autolink.cpp. \sa Inside a see also section any word is checked, so EType, Val1, GVal1, ˜Test and member will be replaced by links in HTML. */ class Test { public: Test(); ˜Test(); void member(int); void member(int,int); //!< //!< /**< /**< constructor destructor A member function. Details. */ An overloaded member function. Details */ /** An enum type. More details */ enum EType { Val1, /**< enum value 1 */ Val2 /**< enum value 2 */ }; protected: int var; /**< A member variable */ }; /*! details. */ Test::Test() { } /*! details. */ Test::˜Test() { } /*! A global variable. */ int globVar; /*! A global enum. */ enum GlobEnum { GVal1, GVal2 }; /*!< global enum value 1 */ /*!< global enum value 2 */ /*! * A macro definition. */ #define ABS(x) (((x)>0)?(x):-(x)) typedef Test B; /*! \fn typedef Test B * A type definition. */ 19.6 typedefs. Typedefs that involve classes, structs and unions, like c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 55 typedef struct StructName TypeName create an alias for StructName, so links will be generated to StructName, when either StructName itself or TypeName is encountered. Example: /*! \file restypedef.cpp * An example of resolving typedefs. */ /*! \struct CoordStruct * A coordinate pair. */ struct CoordStruct { /*! The x coordinate */ float x; /*! The y coordinate */ float y; }; /*! Creates a type name for CoordStruct */ typedef CoordStruct Coord; /*! * This function returns the addition of \a c1 and \a c2, i.e: * (c1.x+c2.x,c1.y+c2.y) */ Coord add(Coord c1,Coord c2) { } 20 20.1 Configuration Format A configuration file is a free-form ASCII text file with a structure that is similar to that of a Makefile,: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 20.1 Format 56 @INCLUDE_PATH = my_config_dir The configuration options can be divided into several categories. Below is an alphabetical index of the tags that are recognized followed by the descriptions of the tags grouped by category. ALIASES 20.2 EXCLUDE PATTERNS 20.4 20.15 EXCLUDE SYMLINKS 20.4 ALPHABETICAL INDEX 20.6 EXPAND AS DEFINED 20.14 ALWAYS DETAILED SEC 20.2 EXPAND ONLY PREDEF 20.14 EXT DOC PATHS 20.17 20.15 ALLEXTERNALS BIN ABSPATH 20.17 BINARY TOC 20.7 EXTERNAL GROUPS BRIEF MEMBER DESC 20.2 EXTRA PACKAGES 20.8 EXTRACT ALL 20.2 EXTRACT LOCAL CLASSES 20.2 CALL GRAPH CASE SENSE NAMES 20.16 20.2 CGI NAME 20.17 EXTRACT PRIVATE 20.2 CGI URL 20.17 EXTRACT STATIC 20.2 FILE PATTERNS 20.4 CHM FILE 20.7 CLASS DIAGRAMS 20.16 FILTER SOURCE FILES 20.4 CLASS GRAPH 20.16 FULL PATH NAMES 20.2 COLLABORATION GRAPH 20.16 GENERATE AUTOGEN DEF 20.12 COLS IN ALPHA INDEX 20.6 GENERATE BUGLIST 20.2 COMPACT LATEX 20.8 GENERATE CHI 20.7 COMPACT RTF 20.9 GENERATE DEPRECIATEDLIST 20.2 DETAILS AT TOP 20.2 GENERATE HTML 20.7 DISABLE INDEX 20.7 GENERATE HTMLHELP 20.7 DISTRIBUTE GROUP DOC 20.2 GENERATE LATEX 20.8 DOC ABSPATH 20.17 GENERATE LEGEND 20.16 DOC URL 20.17 GENERATE MAN 20.10 DOT IMAGE FORMAT 20.16 GENERATE PERLMOD 20.13 DOT PATH 20.16 GENERATE RTF DOTFILE DIRS 20.16 GENERATE TAGFILE 20.15 ENABLE PREPROCESSING 20.14 GENERATE TESTLIST 20.2 ENUM VALUES PER LINE 20.7 GENERATE TODOLIST 20.2 ENABLED SECTIONS 20.2 GENERATE TREEVIEW 20.7 EXAMPLE PATH 20.4 GENERATE XML 20.11 EXAMPLE PATTERNS 20.4 GRAPHICAL HIERARCHY 20.16 EXAMPLE RECURSIVE 20.4 HAVE DOT 20.16 EXCLUDE 20.4 HHC LOCATION c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 20.9 20.7 20.1 Format 57 HIDE FRIEND COMPOUNDS 20.2 MULTILINE CPP IS BRIEF 20.2 HIDE IN BODY DOCS 20.2 OPTIMIZE OUTPUT FOR C 20.2 HIDE SCOPE NAMES 20.2 OPTIMIZE OUTPUT JAVA 20.2 HIDE UNDOC CLASSES 20.2 OUTPUT DIRECTORY 20.2 HIDE UNDOC MEMBERS 20.2 OUTPUT LANGUAGE 20.2 PAPER TYPE 20.8 20.8 HIDE UNDOC RELATIONS 20.16 HTML ALIGN MEMBERS 20.7 PDF HYPERLINKS HTML FOOTER 20.7 PERL PATH 20.15 HTML HEADER 20.7 PERLMOD LATEX 20.13 HTML OUTPUT 20.7 PERLMOD PRETTY 20.13 HTML STYLESHEET 20.7 PERLMOD MAKEVAR PREFIX 20.13 IGNORE PREFIX 20.6 PREDEFINED 20.14 IMAGE PATH 20.4 PROJECT NAME 20.2 INCLUDE GRAPH 20.16 PROJECT NUMBER 20.2 INCLUDE PATH 20.14 QUIET 20.3 INHERIT DOCS 20.2 RECURSIVE 20.4 INLINE INFO 20.2 REFERENCED BY RELATION 20.5 INLINE INHERITED MEMB 20.2 REFERENCES RELATION 20.5 INLINE SOURCES 20.5 REPEAT BRIEF 20.2 INPUT 20.4 RTF EXTENSIONS FILE 20.9 INPUT FILTER 20.4 RTF HYPERLINKS 20.9 INTERNAL DOCS 20.2 RTF OUTPUT 20.9 JAVADOC AUTOBRIEF 20.2 RTF STYLESHEET FILE 20.9 LATEX BATCHMODE 20.8 SEARCH INCLUDES 20.14 LATEX CMD NAME 20.8 SEARCHENGINE 20.17 LATEX HEADER 20.8 SHORT NAMES 20.2 LATEX HIDE INDICES 20.8 SHOW INCLUDE FILES 20.2 LATEX OUTPUT 20.8 SHOW USED FILES 20.2 MACRO EXPANSION MAKEINDEX CMD NAME 20.14 20.8 SKIP FUNCTION MACROS 20.14 SORT MEMBER DOCS 20.2 MAN EXTENSION 20.10 SOURCE BROWSER 20.5 MAN LINKS 20.10 STRIP CODE COMMENTS 20.5 MAN OUTPUT 20.10 STRIP FROM PATH 20.2 MAX DOT GRAPH DEPTH 20.16 TAB SIZE 20.2 MAX DOT GRAPH HEIGHT 20.16 TAGFILES 20.15 MAX DOT GRAPH WIDTH 20.16 TEMPLATE RELATIONS 20.16 MAX INITIALIZER LINES 20.2 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 TOC EXPAND 20.7 20.2 General options 58 TREEVIEW WIDTH 20.7 USE WINDOWS ENCODING 20.2 VERBATIM HEADERS 20.2 WARN FORMAT 20.3 WARN IF DOC ERROR 20.3 WARN IF UNDOCUMENTED 20.3 20.2 WARN LOGFILE 20.3 WARNINGS 20.3 XML DTD 20.11 XML OUTPUT 20.11 XML SCHEMA 20.11 General LANGUAGE The OUTPUT LANGUAGE tag is used to specify the language in which all documentation generated by doxygen is written. Doxygen will use this information to generate all constant output in the proper language. The default language is English, other supported languages are: Brazilian, Chinese, Croatian, Czech, Danish, Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish, and Ukrainian. USE WINDOWS ENCODING)..3.2, written by Dimitri van Heesch 1997-2003 20.2 General options. BRIEF MEMBER DESC If the BRIEF MEMBER DESC tag is set to YES (the default) doxygen will include brief member descriptions after the members that are listed in the file and class documentation (similar to JavaDoc). Set to NO to disable this. REPEAT BRIEF. If the FULL PATH NAMES tag is set to YES then the STRIP FROM PATH tag can be used to strip a user-defined part of the path. Stripping is only done if one of the specified strings matches the left-hand part of the path. INTERNAL DOCS The INTERNAL DOCS tag determines if documentation that is typed after a \internal command is included. If the tag is set to NO (the default) then the documentation will be excluded. Set it to YES to include the internal documentation. CASE SENSE NAMES If the CASE SENSE NAMES tag is set to NO (the default) then doxygen will only generate file names in lower-case letters. If set to YES upper-case letters are also allowed. This is useful if you have classes or files whose names only differ in case and if your file system supports case sensitive file names. SHORT NAMES If the SHORT NAMES tag is set to YES, doxygen will generate much shorter (but less readable) file names. This can be useful is your file systems doesn’t support long names like on DOS, Mac, or CD-ROM. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 59 20.2 General options HIDE SCOPE NAMES If the HIDE SCOPE NAMES tag is set to NO (the default) then doxygen will show members with their full class and namespace scopes in the documentation. If set to YES the scope will be hidden. VERBATIM HEADERS If the VERBATIM HEADERS tag is set the YES (the default) then doxygen will generate a verbatim copy of the header file for each class for which an include is specified. Set to NO to disable this. See also: Section \class. SHOW INCLUDE FILES If the SHOW INCLUDE FILES tag is set to YES (the default) then doxygen will put a list of the files that are included by a file in the documentation of that file.. MULTILINE CPP IS BRIEF. Note that setting this tag to YES also means that rational rose comments are not recognised any more. DETAILS AT TOP If the DETAILS AT TOP tag is set to YES then Doxygen will output the detailed description near the top, like JavaDoc. If set to NO, the detailed description appears after the member documentation. INHERIT DOCS If the INHERIT DOCS tag is set to YES (the default) then an undocumented member inherits the documentation from any documented member that it reimplements. INLINE INFO If the INLINE INFO tag is set to YES (the default) then a tag [inline] is inserted in the documentation for inline members. SORT MEMBER DOCS If the SORT MEMBER DOCS tag is set to YES (the default) then doxygen will sort the (detailed) documentation of file and class members alphabetically by member name. If set to NO the members will appear in declaration order. DISTRIBUTE GROUP DOC. TAB SIZE the TAB SIZE tag can be used to set the number of spaces in a tab. Doxygen uses this value to replace tabs by spaces in code fragments. ENABLED SECTIONS The ENABLED SECTIONS tag can be used to enable conditional documentation sections, marked by \if <section-label> ... \endif blocks.. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 60 20.3 Options related to warning and progress messages GENERATE BUGLIST The GENERATE BUGLIST tag can be used to enable (YES) or disable (NO) the bug list. This list is created by putting \bug commands in the documentation. ALIASES.. OPTIMIZE OUTPUT FOR C JAVA Set the OPTIMIZE OUTPUT JAVA tag to YES if your project consists of Java sources only. Doxygen will then generate output that is more tailored for Java. For instance, namespaces will be presented as packages, qualified scopes will look different, etc. SHOW USED FILES Set the SHOW USED FILES tag to NO to disable the list of files generated at the bottom of the documentation of classes and structs. If set to YES the list will mention the files that were used to generate the documentation. 20. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 61 20.4 20.4 Input related options RECURSIVE The RECURSIVE tag can be used to specify whether or not subdirectories should be searched for input files as well. Possible values are YES and NO. If left blank NO is used. EXCLUDE The EXCLUDE tag can be used to specify files and/or directories that should excluded from the INPUT source files. This way you can easily exclude a subdirectory from a directory tree whose root is specified with the INPUT tag. EXCLUDE SYMLINKS The EXCLUDE SYMLINKS tag can be used select whether or not files or directories that are symbolic links (a Unix filesystem feature) are excluded from the input. EXCLUDE PATTERNS If the value of the INPUT tag contains directories, you can use the EXCLUDE PATTERNS tag to specify one or more wildcard patterns to exclude certain files from those directories. EXAMPLE PATH The EXAMPLE PATH tag can be used to specify one or more files or directories that contain example code fragments that are included (see the \include command in section \include). EXAMPLE RECURSIVE PATTERNS If the value of the EXAMPLE PATH tag contains directories, you can use the EXAMPLE PATTERNS tag to specify one or more wildcard pattern (like ∗.cpp and ∗.h) to filter out the source-files in the directories. If left blank all files are included. IMAGE PATH The IMAGE PATH tag can be used to specify one or more files or directories that contain images that are to be included in the documentation (see the \image command). INPUT FILTER. FILTER SOURCE FILES If the FILTER SOURCE FILES tag is set to YES, the input filter (if set using INPUT FILTER ) will be used to filter the input files when producing source files to browse. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 62 20.5 20.5 Source browsing related options Source browsing related options SOURCE BROWSER If the SOURCE BROWSER tag is set to YES then a list of source files will be generated. Documented entities will be cross-referenced with these sources. INLINE SOURCES Setting the INLINE SOURCES tag to YES will include the body of functions, classes and enums directly into the documentation. STRIP CODE COMMENTS Setting the STRIP CODE COMMENTS tag to YES (the default) will instruct doxygen to hide any special comment blocks from generated source code fragments. Normal C and C++ comments will always remain visible. REFERENCED BY RELATION If the REFERENCED BY RELATION tag is set to YES (the default) then for each documented function all documented functions referencing it will be listed. REFERENCES RELATION If the REFERENCES RELATION tag is set to YES (the default) then for each documented function all documented entities called/used by that function will be listed. 20.6 Alphabetical index options ALPHABETICAL INDEX If the ALPHABETICAL INDEX tag is set to YES, an alphabetical index of all compounds will be generated. Enable this if the project contains a lot of classes, structs, unions or interfaces. COLS IN ALPHA INDEX If the alphabetical index is enabled (see ALPHABETICAL INDEX) then the COLS IN ALPHA INDEX tag can be used to specify the number of columns in which this list will be split (can be a number in the range [1..20]) IGNORE PREFIX. 20.7 HTML related options GENERATE HTML If the GENERATE HTML tag is set to YES (the default) doxygen will generate HTML output HTML OUTPUT The HTML OUTPUT tag is used to specify where the HTML docs will be put. If a relative path is entered the value of OUTPUT DIRECTORY will be put in front of it. If left blank ‘html’ will be used as the default path. HTML FILE EXTENSION The HTML FILE EXTENSION tag can be used to specify the file extension for each generated HTML page (for example: .htm, .php, .asp). If it is left blank doxygen will generate files with .html extension. HTML HEADER The HTML HEADER tag can be used to specify a user-defined HTML header file for each generated HTML page. To get valid HTML the header file should contain at least a <HTML> and a <BODY> tag, but it is good idea to include the style sheet that is generated by doxygen as well. Minimal example: <HTML> <HEAD> <TITLE>My title</TITLE> <LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css"> </HEAD> <BODY BGCOLOR="#FFFFFF"> c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 63 20.7 HTML related options If the tag is left blank doxygen will generate a standard header. header that doxygen normally uses. HTML FOOTER The HTML FOOTER tag can be used to specify a user-defined HTML footer for each generated HTML page. To get valid HTML the header file should contain at least a </BODY> and a </HTML> tag. A minimal example: </BODY> </HTML> If the tag is left blank doxygen will generate a standard footer. on Windows. The HTML Help Workshop contains a compiler that can convert all HTML output generated by doxygen into a single compressed HTML file (.chm). Compressed HTML files are now used as the Windows 98 help format, and will replace the old Windows help format (.hlp) on all Windows platforms in the future. Compressed HTML files also contain an index, a table of contents, and you can search for words in the documentation (which basically renders doxysearch obsolete on Windows). The HTML workshop also contains a viewer for compressed HTML files. CHM FILE. HHC LOCATION. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 64 20.8 LaTeX related options GENERATE CHI If the GENERATE HTMLHELP tag is set to YES, the GENERATE CHI flag controls if a separate .chi index file is generated (YES) or that it should be included in the master .chm file (NO). pannel c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 65 20.9 RTF related options EXTRA_PACKAGES = times If left blank no extra packages will be included. LATEX HEADER The LATEX HEADER tag can be used to specify a personal LATEX header for the generated LATEX document. The header should contain everything until the first chapter. If it is left blank doxygen will generate a standard header. See section Doxygen usage for information on how to let doxygen write the default header to a separate file. Note: Only use a user-defined header if you know what you are doing!)..9 RTF related options GENERATE RTF If the GENERATE RTF tag is set to YES doxygen will generate RTF output. The RTF output is optimised If the RTF HYPERLINKS tag is set to YES, the RTF that is generated will contain hyperlink fields. The RTF file will contain links (just like the HTML output) instead of page references. This makes the output suitable for online browsing using Word or some other Word compatible reader that support those fields. note: WordPad (write) and others do not support links. RTF STYLESHEET FILE Load stylesheet definitions from file. Syntax is similar to doxygen’s config file, i.e. a series of assigments. You only have to provide replacements, missing definitions are set to their default value. See also section Doxygen usage for information on how to generate the default style sheet that doxygen normally uses. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 66 20.10 Man page related options RTF EXTENSIONS FILE Set optional variables used in the generation of an RTF document. Syntax is similar to doxygen’s config file. A template extensions file can be generated using doxygen -e rtf extensionFile. 20.10.11. 20.12.13 PERLMOD related options GENERATE PERLMOD If the GENERATE PERLMOD tag is set to YES Doxygen will generate a Perl module file that captures the structure of the code including all documentation. Note that this feature is still experimental and incomplete at the moment. PERLMOD LATEX If the PERLMOD LATEX tag is set to YES Doxygen will generate the necessary Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI output from the Perl module output. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 67 20.14 Preprocessor related options PERLMOD PRETTY MAKEVAR PREFIX. 20.15 External reference options TAGFILES The TAGFILES tag can be used to specify one or more tagfiles. See section Doxytag usage for more information about the usage of tag files." ... c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 68 20.16 Dot options where loc1 and loc2 can be relative or absolute paths or URLs, If a location is present for each tag, the installdox tool .16 Dot options CLASS DIAGRAMS If the CLASS DIAGRAMS tag is set to YES (the default) doxygen will generate a class diagram (in HTML and LATEX) for classes with base or super classes. Setting the tag to NO turns the diagrams off. Note that this option is superceded by the HAVE DOT option below. This is only a fallback. It is recommended to install and use dot, since it yields more powerful graphs.. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 69 20.17 Search engine options CALL GRAPH. GRAPHICAL HIERARCHY If the GRAPHICAL HIERARCHY and HAVE DOT tags are set to YES then doxygen will graphical hierarchy of all classes instead of a textual one.). MAX DOT GRAPH HEIGHT DEPTH fot the depth value (the default), the graph is not depth-constraint. MAX DOT GRAPH WIDTH..17 Search engine options SEARCHENGINE The SEARCHENGINE tag specifies whether or not a search should be used. Possible values are YES and NO. If set to NO or left blank, the values of all other tags in this section will be ignored. CGI NAME The CGI NAME tag should be the name of the CGI script that starts the search engine (doxysearch) with the correct parameters. A script with this name will be generated by doxygen. CGI URL The CGI URL tag should be the absolute URL to the directory where the cgi binaries are located. See the documentation of your HTTP daemon for details. DOC URL The DOC URL tag should be the absolute URL to the directory where the documentation is located. If left blank the absolute path to the documentation, with file:// prepended to it, will be used. This is correct for local viewing only. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 70 20.17 Search engine options DOC ABSPATH The DOC ABSPATH tag should be the absolute path to the directory where the documentation is located. If left blank the directory on the local machine will be used. BIN ABSPATH The BIN ABSPATH tag must point to the directory where the doxysearch binary is installed. EXT DOC PATHS The EXT DOC PATHS tag can be used to specify one or more paths to documentation generated for other projects. This allows doxysearch to search the documentation for these projects as well. All paths must be absolute. CGI_NAME CGI_URL DOC_URL DOC_ABSPATH BIN_ABSPATH = = = = = = = = = = = = = = QdbtTabular html YES examples/examples.doc src *.cc *.h examples qt.tag /usr/local/bin/perl YES search.cgi˜dimitri/cgi-bin˜dimitri/qdbttabular /home/dimitri/.html/qdbttabular /home/dimitri/bin To regenerate the Qt-1.44 documentation from the sources, you could use the following config file: PROJECT_NAME OUTPUT_DIRECTORY HIDE_UNDOC_MEMBERS HIDE_UNDOC_CLASSES ENABLE_PREPROCESSING MACRO_EXPANSION EXPAND_ONLY_PREDEF SEARCH_INCLUDES FULL_PATH_NAMES STRIP_FROM_PATH PREDEFINED = = = = = = = = = = = Qt qt_docs YES YES YES YES YES YES YES $(QTDIR)/ USE_TEMPLATECLASS Q_EXPORT= \ QArrayT:=QArray \ c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 71 72 INPUT = FILE_PATTERNS INCLUDE_PATH RECURSIVE = = =. 21 Special Commands 21.1 Introduction All commands in the documentation start with a backslash (\) or an at-sign (@). If you prefer you can replace all commands starting with a backslash below, by their counterparts that start with an at-sign. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 21.1 Introduction 73.75 \endlatexonly 21.86 \addindex 21.58 \endlink 21.60 21.2 \endverbatim 21.87 \anchor 21.59 \endxmlonly 21.88 \arg 21.76 \enum 21.7 \attention 21.29 \example 21.8 \author 21.30 \exception 21.38 \b 21.77 \f$ 21.89 \brief 21.31 \f[ 21.90 \bug 21.32 \f] 21.91 \c 21.78 \file 21.9 \callgraph 21.3 \fn 21.10 \class 21.4 \hideinitializer 21.11 \code 21.79 \htmlinclude 21.74 \copydoc 21.80 \htmlonly 21.92 \date 21.33 \if 21.39 \def 21.5 \ifnot 21.40 \defgroup 21.6 \image 21.93 \deprecated 21.34 \include 21.68 \dontinclude 21.67 \ingroup 21.12 \dotfile 21.81 \internal 21.14 \e 21.82 \invariant 21.41 \else 21.35 \interface 21.13 \elseif 21.36 \latexonly 21.94 \em 21.83 \li 21.95 \endcode 21.84 \line 21.69 \endhtmlonly 21.85 \link 21.61 \endif 21.37 \mainpage 21.15 \addtogroup c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 21.2 \addtogroup <name> [(title)] 74 \n 21.96 \struct 21.24 \name 21.16 \subsection 21.64 \namespace 21.17 \subsubsection 21.65 \nosubgrouping 21.18 \test 21.52 \note 21.42 \throw 21.53 \overload 21.19 \todo 21.54 \p 21.97 \typedef 21.25 \package 21.20 \union 21.26 \page 21.21 \until 21.72 \par 21.43 \var 21.27 \param 21.44 \verbatim 21.98 \post \verbinclude 21.73 21.45 21.46 \version 21.55 \pre \warning 21.56 \ref 21.62 \weakgroup 21.28 \relates 21.22 \xmlonly 21.99 \remarks 21.47 \xrefitem 21.57 \return 21.48 \retval 21.49 \sa 21.50 \section 21.63 \showinitializer \$ 21.104 \@ 21.101 \\ 21.100 \& 21.103 21.23 \∼ 21.102 \since 21.51 \< 21.106 \skip 21.70 \> 21.107 \skipline 21.71 \# 21.105’ c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 21.3 \callgraph * @{ */ /*! *. 21.5 \def <name> Indicates that a comment block contains documentation for a #define macro. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 75 21.6 \defgroup <name> (group title) Example: /*! \file define.h \brief testing defines This is to test the documentation of defines. */ /*! \def MAX(x,y).6 .7 . */ /*! \enum Test::TEnum * A description of the enum type. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 76 21.8 \example <file-name> */ /*! \var Test::TEnum Test::Val1 * The description of the first enum value. */ 21.8 ..9 \file [<name>] Indicates that a comment block contains documentation for a source or header file with name <name>. The file name may include (part of) the path if the file-name alone is not unique. If the file name is omitted (i.e. the line after \file is left blank) then the documentation block that contains the \file command will belong to the file it is located in. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 77 21.10 \fn (function declaration); 21.10 . See also: section \var and \typedef. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 78 21.11 \hideinitializer 21.12 .13 \interface Indicates that a comment block contains documentation for an interface with name <name>. The arguments are equal to the \class command. See also: section \class. 21.14 \internal This command writes the message ‘For internal use only’ to the output and all text after a \internal command until the end of the comment block is ignored. You can use INTERNAL DOCS in the config file to show or hide the internal documentation. 21.15  Introduction * * This is the introduction. * * \section install Installation * * \subsection step1 Step 1: Opening the box * * etc... */ c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 79 21.16 \name (header) You can refer to the main page using \ref index (if the treeview is disabled, otherwise you should use \ref main). See also: section \section, section \subsection and section \page. 21.16 \name (header) This command turns a comment block into a header definition of a member group. The comment block should be followed by a //@{ ... //@} block containing the members of the group. See section Member Groups for an example. 21.17 \namespace <name> Indicates that a comment block contains documentation for a namespace with name <name>. 21.18 \nosubgrouping This command can be put in the documentation of a class. It can be used in combination with member grouping to avoid that doxygen puts a member group as a subgroup of a Public/Protected/Private/... section. 21.19 . Example: class Test { public: void drawRect(int,int,int,int); void drawRect(const Rect &r); }; void Test::drawRect(int x,int y,int w,int h) {} void Test::drawRect(const Rect &r) {} c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 80 21.20 \package <name> /*! .20 \package <name> Indicates that a comment block contains documentation for a Java package with name <name>. 21.21 . See also: section \section, section \subsection, and section \ref. 21.22 \relates <name> This command can be used in the documentation of a non-member function <name>. It puts the function inside the ‘related function’ section of the class documentation. This command is useful for documenting c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 81 21.23 \showinitializer.23 .24 \struct <name> [<header-file>] [<header-name>] Indicates that a comment block contains documentation for a struct with name <name>. The arguments are equal to the \class command. See also: section \class. 21.25 \typedef (typedef declaration) Indicates that a comment block contains documentation for a typedef (either global or as a member of a class). This command is equivalent to \var and \fn. See also: section \fn and \var. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 82 21.26 \union <name> [<header-file>] [<header-name>] 21.26 \union <name> [<header-file>] [<header-name>] Indicates that a comment block contains documentation for a union with name <name>. The arguments are equal to the \class command. See also: section \class. 21.27 \var (variable declaration) Indicates that a comment block contains documentation for a variable or enum value (either global or as a member of a class). This command is equivalent to \typedef and \fn. See also: section \fn and \typedef. 21.28 \weakgroup <name> [(title)] Can be used exactly like \addtogroup, but has a lower priority when it comes to resolving conflicting grouping definitions. See also: page Grouping and \addtogroup. Section indicators 21.29 .30 . c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 83 21.31 \brief {brief description} * \warning This class may explode in your face. * \warning If you inherit anything from this class, you’re doomed. */ class WindowsNT {}; 21.31 .32  ends when a blank line or some other sectioning command is encountered. See section \author for an example. 21.33 .34 \deprecated { description } Starts a paragraph indicating that this documentation block belongs to a deprecated entity. Can be used to describe alternatives, expected life span, etc. 21.35 \else Starts a conditional section if the previous conditional section was not enabled. The previous section should have been started with a \if, \ifnot, or \elseif command. See also: \if, \ifnot, \elseif, \endif. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 84 21.36 \elseif <section-label> 21.36 .37 \endif Ends a conditional section that was started with \if or \ifnot For each \if or \ifnot one and only one matching \endif must follow. See also: \if, and \ifnot. 21.38 .39 : c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 85 21.40 \ifnot <section-label>. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 101 102. • </CODE> End a <CODE> section. • <DD> Starts an item description. • <DFN> Starts a piece of text displayed in a typewriter font. • </DFN> Ends a <DFN> section.. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 103: c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 104 • © the copyright symbol • " a double quote. ”s) to the output. • &?cedil; where ? is one of {c,C}, writes a c-cedille (like ç). • &?ring; where ? is one of {a,A}, writes an a with a ring (like å). • a non breakable space. Finally, to put invisible comments inside comment blocks, HTML style comments can be used: /*! <!-- This is a comment with a comment block --> Visible text */ Part III Developers Manual 23 Doxygen’s Internals Doxygen’s internals Note that this section is still under construction! The following picture shows how source files are processed by doxygen. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 105.3.2, written by Dimitri van Heesch 1997-2003 106.3.2, written by Dimitri van Heesch 1997-2003 107.3.2, written by Dimitri van Heesch 1997-2003 108 print STDERR "Error: opening file Makefile.libdoxygen for writing\n"; exit 1; } print "Processing Makefile.libdoxygen...\n"; while (<F>) { if ( s/\(LEX\) -P([a-z]+)YY -t $file/(LEX) -d -P\1YY -t $file/g ) { print "Enabling debug info for $file\n"; } elsif ( s/\(LEX\) -d -P([a 24. 24.3.2, written by Dimitri van Heesch 1997-2003 24. 24. 24.3.2, written by Dimitri van Heesch 1997-2003 109 24.3 Perl Module documentation format. This should generate a doxylatex.pdf with the documentation in PDF format. 5. Run: make dvi This should generate a doxylatex.dvi with the documentation in DVI format. 24. 24. 25 Internationalization Support for multiple languages Doxygen has built-in support for multiple languages. This means that the text fragments that doxygen generates can be produced in languages other than English (the default) at configuration time. Currently (version 1.3.2), 28 languages are supported (sorted alphabetically): Brazilian Portuguese, Catalan, Chinese, Chinese Traditional, Croatian, Czech, Danish, Dutch, English, Finnish, French, German, c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 110 111 Greek, Hungarian, Italian, Japanese, Korean, Norwegian,. Language Brazilian Portuguese Catalan Chinese Chinese Traditional Croatian Czech Danish Dutch English Finnish French German Greek Hungarian Italian Japanese Korean Norwegian Polish Portuguese Romanian Russian Serbian Slovak Slovene Spanish Swedish Ukrainian Maintainer Fabio ”FJTC” Jun Takada Chino Albert Mora Wei Liu Wang Weihan Harry Kalogirou Földvári György Alessandro Falappa Ahmed Aldo Faisal Ryunosuke Satoh Kenji Nagamatsu Richard Kim Lars Erik Jordet Francisco Oltra Thennet XeT Erixon Olexij Tkatchenko Contact address [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] g [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected] [email protected]. Adding a new language to doxygen to Doxygen: This short HOWTO explains how to add support for a new language c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 Status 1.3.1 1.2.17 1.2.13 1.2.16 1.3.1 up-to-date strange up-to-date up-to-date obsolete up-to-date 1.3.1 1.2.11 1.2.1 up-to-date strange strange 1.2.2 strange 1.3.1 1.2.16 strange 1.2.17 1.2.18 1.2.16 1.2.7 obsolete 1.2.11 112 be. in the #ifndef and #define preprocessor commands at the beginning of the file).. c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 113 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 114.pl perl script was developed (located in doxygen/doc directory). It extracts the important information about obsolete and new methods from the source files for each of the languages. The information is stored in the translator report ASCII file (doxygen/doc/translator report.txt). Looking at the base class of the language translator, the script guesses also the status of the translator – see the last column of the table with languages above. The translator.pl.pl, and have a look at the translator report (ASCII c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 115.pl again)., look at the translator report generated by the translator.pl script and choose one of the missing method that is implemented by the translator adapter, that is used as your base class. When there is not such a method in your translator adapter base class, you probably can change the translator adapter base to the newer one. Probably the easiest approach of the gradual update is to look at the translator report to the part where the list of the implemented translator adapters is shown. Then: • Look how many required methods each adapter implements and guess how many methods you are willing to update (to spend the time with). • Choose the related oldest translator adapters to be removed (i.e. not used by your translator). • Change the base class of your translator class to the translator adapter that you want to use. • Implement the methods that were implemented by the older translator adapters. Notice: Do not blindly implement all methods that are implemented by your translator adapter base class. The reason is that the adapter classes implement also obsolete methods. Another reason is that some of the methods could become obsolete from some newer adapter on. Focus on the methods listed as required. The really obsolete language translators may lead to too much.3.2, written by Dimitri van Heesch 1997-2003 Index \#, 100 \$, 100 \&, 100 \<, 101 \>, 101 \\, 100 \a, 94 \addindex, 90 \addtogroup, 74, 83 \anchor, 90 \arg, 94 \attention, 83 \author, 83 \b, 95 \brief, 84 \bug, 84 \c, 95 \callgraph, 75 \class, 75 \code, 95 \copydoc, 95 \date, 84 \def, 75 \defgroup, 76 \deprecated, 84 \dontinclude, 91 \dotfile, 96 \e , 96 \else, 84 \elseif, 85 \em , 96 \endcode, 96 \endhtmlonly, 96 \endif, 85 \endlatexonly, 97 \endlink , 90 \endverbatim, 97 \endxmlonly, 97 \enum, 76 \example, 77 \exception, 85 \f$, 97 \f[, 97 \f], 97 \file, 77 \fn, 78 \hideinitializer, 79 \htmlinclude, 94 \htmlonly, 97 \if, 85 \ifnot, 86 \image, 98 \include, 92 \ingroup, 79 \interface, 79 \internal, 79 \invariant, 86 \latexonly, 98 \li, 99 \line, 93 \link, 90 \mainpage, 79 \n, 99 \namespace, 80 \nosubgrouping, 80 \note, 86 \overload, 80 \p, 99 \package, 81 \page, 81 \par, 86 \paragraph, 91 \param, 87 \post, 87 \pre, 87 \ref, 90 \relates, 81 \remarks, 88 \return, 88 \retval, 88 \sa, 88 \section, 91 \showinitializer, 82 \since, 88 \skip, 93 \skipline, 93 \struct, 82 \subsection, 91 \subsubsection, 91 \test, 88 \throw, 89 \todo, 89 \typedef, 82 \union, 83 \until, 93 \var, 83 \verbatim, 99 \verbinclude, 93 \version, 89 \warning, 89 \xmlonly, 100 \xrefitem, 89 INDEX \∼, 100 acknowledgements, 3 ALIASES, 61 ALLEXTERNALS, 69 ALPHABETICAL INDEX, 63 ALWAYS DETAILED SEC, 59 BIN ABSPATH, 71 BINARY TOC, 65 bison, 4 BRIEF MEMBER DESC, 59 browser, 13 CALL GRAPH, 70 CASE SENSE NAMES, 59 CGI NAME, 70 CGI URL, 70 CHM FILE, 64 CLASS DIAGRAMS, 69 CLASS GRAPH, 69 COLLABORATION GRAPH, 69 COLS IN ALPHA INDEX, 63 COMPACT LATEX, 65 COMPACT RTF, 66 DETAILS AT TOP, 60 DISABLE INDEX, 65 DISTRIBUTE GROUP DOC, 60 Doc++, 3 DOC ABSPATH, 71 DOC URL, 70 DOT CLEANUP, 70 DOT IMAGE FORMAT, 70 DOT PATH, 70 DOTFILE DIRS, 70 ENABLE PREPROCESSING, 68 ENABLED SECTIONS, 60 ENUM VALUES PER LINE, 65 EXAMPLE PATH, 62 EXAMPLE PATTERNS, 62 EXAMPLE RECURSIVE, 62 EXCLUDE, 62 EXCLUDE PATTERNS, 62 EXCLUDE SYMLINKS, 62 EXPAND AS DEFINED, 68 EXPAND ONLY PREDEF, 68 EXT DOC PATHS, 71 EXTERNAL GROUPS, 69 EXTRA PACKAGES, 65 EXTRACT ALL, 58 EXTRACT LOCAL CLASSES, 58 EXTRACT PRIVATE, 58 EXTRACT STATIC, 58 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 117 features, 41 FILE PATTERNS, 62 FILTER SOURCE FILES, 62 flex, 4 FULL PATH NAMES, 59 GENERATE AUTOGEN DEF, 67 GENERATE BUGLIST, 61 GENERATE CHI, 65 GENERATE DEPRECATEDLIST, 60 GENERATE HTML, 63 GENERATE HTMLHELP, 64 GENERATE LATEX, 65 GENERATE LEGEND, 70 GENERATE MAN, 67 GENERATE PERLMOD, 67 GENERATE RTF, 66 GENERATE TAGFILE, 69 GENERATE TESTLIST, 60 GENERATE TODOLIST, 60 GENERATE TREEVIEW, 65 GENERATE XML, 67 GPL, 2 GRAPHICAL HIERARCHY, 70 HAVE DOT, 69 HHC LOCATION, 64 HIDE FRIEND COMPOUNDS, 59 HIDE IN BODY DOCS, 59 HIDE SCOPE NAMES, 60 HIDE UNDOC CLASSES, 59 HIDE UNDOC MEMBERS, 59 HIDE UNDOC RELATIONS, 69 HTML ALIGN MEMBERS, 64 HTML FILE EXTENSION, 63 HTML FOOTER, 64 HTML HEADER, 63 HTML OUTPUT, 63 HTML STYLESHEET, 64 IGNORE PREFIX, 63 IMAGE PATH, 62 INCLUDE GRAPH , 69 INCLUDE PATH, 68 INCLUDED BY GRAPH , 69 INHERIT DOCS, 60 INLINE INFO , 60 INLINE INHERITED MEMB, 59 INLINE SOURCES, 63 INPUT, 62 INPUT FILTER, 62 installation, 4 INTERNAL DOCS, 59 JAVADOC AUTOBRIEF, 60 INDEX LaTeX, 13 LATEX BATCHMODE, 66 LATEX CMD NAME, 65 LATEX HEADER, 66 LATEX HIDE INDICES, 66 LATEX OUTPUT, 65 LATEX PDFLATEX, 66 license, 2 MACRO EXPANSION, 68 make, 4 MAKEINDEX CMD NAME, 65 MAN LINKS, 67 MAN OUTPUT, 67 MAX DOT GRAPH DEPTH, 70 MAX DOT GRAPH HEIGHT, 70 MAX DOT GRAPH WIDTH, 70 MAX EXTENSION, 67 MAX INITIALIZER LINES, 61 MULTILINE CPP IS BRIEF, 60 OPTIMIZE OUTPUT FOR C, 61 OPTIMIZE OUTPUT JAVA, 61 output formats, 51 OUTPUT DIRECTORY, 58 OUTPUT LANGUAGE, 58 PAPER TYPE, 65 parsing, 14 PDF HYPERLINKS, 66 perl, 4 PERL PATH, 69 perlmod, 108 PERLMOD LATEX, 67 PERLMOD MAKEVAR PREFIX, 68 PERLMOD PRETTY, 68 PREDEFINED, 68 PROJECT NAME, 58 PROJECT NUMBER, 58 Qt, 4 QUIET, 61 RECURSIVE, 62 REFERENCED BY RELATION, 63 REFERENCES RELATION, 63 REPEAT BRIEF, 59 RTF HYPERLINKS, 66 RTF OUTPUT, 66 RTF STYLESHEET FILE, 66 SEARCH INCLUDES , 68 SEARCHENGINE, 70 SHORT NAMES, 59 SHOW INCLUDE FILES, 60 c User Manual for Doxygen 1.3.2, written by Dimitri van Heesch 1997-2003 118 SHOW USED FILES, 61 SKIP FUNCTION MACROS, 68 SORT MEMBER DOCS, 60 SOURCE BROWSER, 63 STRIP CODE COMMENTS, 63 STRIP FROM PATH, 59 TAB SIZE, 60 TAGFILES, 68 TEMPLATE RELATIONS, 69 TOC EXPAND, 65 TREEVIEW WIDTH, 65 USE WINDOWS ENCODING, 58 VERBATIM HEADERS, 60 WARN FORMAT, 61 WARN IF UNDOCUMENTED, 61 WARN LOGFILE, 61 WARNINGS, 61 XML DTD, 67 XML OUTPUT, 67 XML SCHEMA, 67
* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project