Home

Manual for version 1.2.8.1 Written by Dimitri van Heesch c 1997-2001

1. The IMAGE_PATH tag 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 The INPUT FILTER tag can be used to specify a program that doxygen should invoke to filter for each input file Doxygen will invoke the filter program by executing via popen the command filter input file where filter is the value of the INPUT FILTER tag and lt input file gt is the name of an input file Doxygen will then use the output that the filter program writes to standard output FILTER SOURCE FILES Ifthe 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 21 5 Alphabetical index options ALPHABETICAL_INDEX Ifthe 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 In case all classes in a project start with a common prefix all classes
2. ERATE CHI Ifthe 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 BINARY TOC If the GENERATE_HTMLHELP tag is set to YES BINARY TCC flag controls whether TOC a binary table of contents is generated YES or a normal table of contents NO in the chm file EXPAND The TOC_EXPAND flag can be set to YES to add extra items for group members to the table of contents of the HTML help documentation and to the tree view DISABLE_INDEX If you want full control over the layout of the generated HTML pages it might be necessary to disable the index and replace it with your own The DISABLE_INDEX tag can be used to turn on off the condensed index at top of each page A value of NO the default enables the index and the value YES disables it ENUM VALUES _PER_LINE This tag can be used to set the number of enum values range 1 20 that doxygen will group on one line in the generated HTML documentation ERATE_TREEVIEW If the GENERATE TREEVIEW tag is set to YES a side pannel will be generated containing a tree like index structure just like the one that is generated for HTML Help For this to work a browser that supports JavaScript and frames is req
3. In block or a Lear 8 block if you prefer C style comments Note that the members of the group should be physcially inside the member group s body Before the opening marker of a block a separate comment block may be placed This block should contain the name or name command and is used to specify the header of the group Optionally the comment block may also contain more detailed information about the group Nesting of member groups is not allowed If all members of a member group inside a class have the same type and protection level for instance all are static public members then the whole member group is displayed as a subgroup of the type protection User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 23 level group the group is displayed as a subsection of the Static Public Members section for instance If two or more members have different types then the group is put at the same level as the automatically generated groups If you want to force all member groups of a class to be at the top level you should put a nosubgrouping command inside the documentation of the class Example A class Details class Test public Same documentation for both members Details void funclInGroupl void func2InGroupl 8 Function without group Details void ungroupedFunction void funclInGroup2 protected void func2InGroup2 1 void
4. 22 69 word Displays the argument word using a typewriter font Use this to refer to a word of code Equivalent to tt word tt User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 70 code Example Typing This function returns c void and not c int will result in the following text This function returns void and not int Equivalent to p 22 70 code Starts a block of code A code block is treated differently from ordinary text It is interpreted as C C code The names of the classes and members that are documented are automatically replaced by links to the documentation See also section endcode section verbatim 22 71 lt word gt Displays the argument lt word gt in italics Use this command to emphasize words Example Typing this is a e really good example will result in the following text this is a really good example Equivalent to em 22 72 Nem lt word gt Displays the argument lt word gt in italics Use this command to emphasize words Example Typing this is a em really good example will result in the following text this is a really good example Equivalent to e User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 88 22 73 endcode 22 73 endcode Ends a block of code See also section code 22 74 endhtmlonly Ends a block of text that
5. 8 Preprocessing Source files that are used as input to doxygen be parsed by doxygen s build in C preprocessor By default doxygen does only partial preprocessing That is it evaluates conditional compilation statements like if and evaluates macro definitions but it does not perform macro expansion So if you have the following code fragment define VERSION 200 define CONST_STRING const char if VERSION gt 200 static CONST_STRING version 2 xx else static CONST_STRING version 1 xx endif User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 28 Then by default doxygen will feed the following to its parser define VERSION define CONST_STRING static CONST_STRING version 2 xx You can disable all preprocessing by setting ENABLE PREPROCESSING to NO in the configuation file In the case above doxygen will then reads both statements In case you want to expand the CONST_STRING macro you should set the MACRO_EXPANSION tag in the config file to YES Then the result after preprocessing becomes define VERSION define CONST_STRING static const char version 1 xx Note that doxygen will now expand all macro definitions recursively if needed This is often too much Therefore doxygen also allows you to expand only those defines that you explicitly specify For this you have to set the EXPAND_ONLY PREDEF tag to YES and specify the macro definitions after th
6. 1 Using in text formulas that appear in the running text These formulas should be put between a pair of f commands so The distance between f x_1l y_1 f and f x_2 y_2 fS is sqrt x 2 x 1 72 2 y 1 2 N S results in The distance between z1 y1 and 2 ya is y 2 z1 yo 1 2 Unnumbered displayed formulas that are centered on a separate line These formulas should be put between M and M commands An example NEL I 2 2Mleft int 0 T psi t left u a t Nint Ngamma t frac d theta theta int_ a theta c xi u_t xi t d xi right dt right Nf results in T a 40 0 I w t fua j f 1 ac dt Formulas should be valid commands in IA TEX 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 in the html directory to a rid of an incorrect formula 7 Graphs and diagrams Doxygen has build in support to generate inheritance diagrams for C classes Doxygen can use the dot tool from graphviz 1 5 to generate more advanced diagrams amp graphs Graphviz is an open sourced cross platform graph drawing toolkit from AT amp T and Lucent Bell Labs and can be found at http www research att com sw tools graphviz If you have the dot tool available in the path you can set HAVE
7. A link to the enumeration type Test EType A link to some enumeration values Test Vall and GVal2 x eS 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 46 20 5 Links to variables typedefs enum types enum values and defines 47 A link to the variable var A link to the global typedef B 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 Vall Vall endlink and GVall And last but not least a link to a file autolink cpp Nsa Inside a see also section any word is checked so EType Vall GVall Test and member will be replaced by links in HTML 7 class Test public Test constructor Test lt destructor void member int A member function Details void member int int An overloaded member function Details An enum type More details enum EType Vall lt enum value 1 Val2 lt enum value
8. ED tag can be used to specify one or more macro names that are defined before the preprocessor is started similar to the D option of gcc The argument of the tag is a list of macros of the form name or name definition no spaces If the definition and the are omitted 21 is assumed EXPAND AS D EFIN ED If the MACRO EXPANSION and 1 EXPAND PR ED EF ONLY tags are set to YES then this tag can be used to specify a list of macro names that should be expanded The macro definition that is found in the sources will be used Use the PRED different macro definition User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 EE IN ED tag if you want to use a 2111 External reference options 21 11 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 Optionally an initial location of the external documentation can be added for each tagfile The format of a tag file without this location is as follows TAGFILES filel file2 Adding location for the tag files is done as follows TAGFILES filel locl file2 loc2 where loci and 1 2 can be relative or absolute paths or URLs If a location is present for each tag the installdox tool see section Installdox usage for more information does not have to be run
9. Test see testMeToo see publicVar return The test results 0X X X F int testMe int char s A pure virtual member Qsee testMe param cl the first argument Qparam c2 the second argument virtual void testMeToo char cl char c2 0 a public variable Details int publicVar User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 3 2 Structural commands a function variable Details a 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 Note Each entity can only have one brief and one detailed description If you specify more than one com ment block of the same type only one will be used and all others are ignored 3 2 Structural commands 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 of one of its members Although
10. Major new features LaTeX output generation Full JavaDoc support Build in C preprocessor for correct conditional parsing of source code that is read by Doxygen Build in HTML to LaTeX converter This allows you to use HTML tags in your documentation while doxygen still generates proper LaTeX output e Many new commands there are now more than 60 to document more entities to make the docu mentation look nicer and to include examples or pieces of examples e Enum types enum values typedefs defines and files can now be documented e Completely new documentation that is now generated by Doxygen e A lot of small examples are now included Version 0 3 Major new features e A search engine doxysearch that allows you to search through the generated documentation e A configuration file instead of command line options A default configuration file can be generated by doxygen e Added an option to generate output for undocumented classes e Added an option to generate output for private members e Every page now contains a condensed index page allowing much faster navigation through the documentation e Global and member variables can now be documented e A project name can now given which will be included in the documentation User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 38 Version 0 2 Major new features Blocks of code are now parsed Function calls and variables are replaced b
11. Manual for version 1 2 8 1 Written by Dimitri van Heesch 1997 2001 CONTENTS Contents 10 11 12 13 14 15 16 17 18 19 20 User Manual Installation Getting started Documenting the code Lists Grouping Including formulas Graphs and diagrams Preprocessing Linking to external documentation Frequently Asked Questions Troubleshooting Reference Manual Features Doxygen History Doxygen usage Doxytag usage Doxysearch usage Doxywizard usage Installdox usage Output Formats Automatic link generation User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 10 13 19 20 24 25 27 30 31 33 35 35 36 38 39 41 43 43 44 44 CONTENTS 21 Configuration 22 Special Commands 23 HTML Commands 24 Internationalization User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 48 66 94 95 CONTENTS Doxygen license Copyright 1997 2001 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 d
12. 1 6 Tools used to develop doxygen Doxygen was developed and tested under Linux using the following open source tools EGCS version 2 91 66 GNU flex version 2 5 4 GNU bison version 1 25 GNU make version 3 76 1 Perl version 5 005 02 VIM version 5 4 Netscape 4 61 Troll Tech s tmake version 1 3 included in the distribution teTeX version 0 9 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 2 4 Step 1 Creating a configuration file 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 configura tion file A project can consist of a single source file but can also
13. Ends a TT section lt KBD gt Starts a piece of text displayed in a typewriter font lt KBD gt Ends a lt KBD gt section lt UL gt Starts an unnumbered item list lt UL gt Ends an unnumbered item list VAR Starts a piece of text displayed in an italic font lt VAR Ends a lt VAR section The special HTML character entities that are recognized by Doxygen e amp copy the copyright symbol e amp quot a double quote e amp uml where is one of A E LO U Y a i 0 u y writes a character with a diaeresis accent like e amp acute where is one of A E 1 0 U Y a e i o u y writes a character with a acute accent like e amp grave where is one of A E 1 0 U a i 0 u y writes a character with a grave accent like amp circ where is one of A E LO U a e i o u y writes a character with a circumflex accent like a amp tilde where is one of A N O a n o writes a character with a tilde accent like 852119 write a sharp s i e s to the output amp cedil where is one of c C writes a c cedille like amp ring where is one of a A writes an a with a ring like amp nbsp a non breakable space 24 Internationalization Support for multiple languages Doxygen has support for multiple languages This means that the text fragments that doxygen generates can changed into languages other than English the default at
14. HIDE_UNDOC_CLASSES 21 2 PERL_PATH 21 11 HIDE_UNDOC_MEMBERS 21 2 PREDEFINED 21 10 HTML ALIGN MEMBERS 21 6 PROJECT NAME 212 HTML FOOTER 21 6 PROJECT NUMBER 212 HTML HEADER 21 6 QUIET 213 HTML_OUTPUT 21 6 RECURSIVE sis HTML STYLESHEET 21 6 REPEAT BRIEKE did IGNORE PREFIX 21 5 GNORETP RTF_EXTENSIONS_FILE 21 8 IMAGE_PATH 21 4 RTF_HYPERLINKS 21 8 INCLUDE_GRAPH 21 12 RTF_OUTPUT 21 8 INCLUDE_PATH 21 10 RTF_STYLESHEET_FILE 21 8 INHERIT_DOCS 21 2 SEARCH_INCLUDES 21 10 INLINE_INFO 242 SEARCHENGINE 21 13 INLINE SOURCES 21 2 SHORT NAMES 21 2 INPUT 21 4 SHOW INCLUDE FILES 21 2 INPUT FILTER 21 4 SHOW USED FILES 21 INTERNAL DOCS 21 2 SORT MEMBER DOCS 21 2 JAVADOC AUTOBRIEF 21 2 SOURCE BROWSER 21 2 LATEX BATCHMODE 21 7 STRIP CODE COMMENTS 21 2 LATEX HEADER 21 7 von or ais STRIP FROM PATH 21 2 MACRO EXPANSION 21 10 IAE STE a MAN_EXTENSION 21 9 TAGPILES 21 11 MAN_LINKS TOC_EXPAND 21 6 MAN OUTPUT 219 TREEVIEW_WIDTH 21 6 MAX_DOT_GRAPH_HEIGHT 21 12 VERBATIM HEADERS 21 2 MAX DOT GRAPH WIDTH 21 12 WARN FORMAT 21 3 MAX INITIALIZER LINES 212 WARN IF UNDOCUMENTED 21 3 OPTIMIZE OUTPUT FOR C 21 2 WARN LOGFILE 21 3 OUTPUT DIRECTORY 21 2 WARNINGS 21 3 21 2 General options User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 22 General options PROJECT_NAME The PROJECT_NAME tag is a single word or a sequence of words surrounded by double quotes that should identify the project for which the
15. 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 doxytag and doxysearch 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 postscript and pdf version of the manual you will need 1atex and dvips and the ghostscript package for this make pdf The postscript manual doxygen manual ps will be located in the latex directory of the distribu tion Just send it to a postscript printer to print it or
16. lt name gt group title Indicates that a comment block contains documentation for a group of classes files or namespaces This can be used to categorize classes files or namespaces and document those categories You can also use groups as members of other groups thus building a hierarchy of groups The lt name gt argument should be a single word identifier See also page Grouping sections ingroup addtogroup weakgroup 22 5 enum lt name gt Indicates that a comment block contains documentation for an enumeration with name lt name gt If the enum is a member of a class and the documentation block is located outside the class definition the scope of the class should be specified as well If a comment block is located directly in front of an enum declaration the enum comment may be omitted Note The type of an anonymous enum cannot be documented but the values of an anonymous enum can Example class Test public enum TEnum Vall Val2 i class Test The class description enum Test TEnum A description of the enum type var Test TEnum Test Vall The description of the first enum value 22 6 example lt file name gt Indicates that a comment block contains documentation for a source code example The name of the source file is lt file name gt The text of this file will be included in the documentation just after the documentation contained in the
17. ported e References to base super classes and inherited overridden members are generated automatically e Includes a fast rank based search engine to search for strings or words in the class and member documentation User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 35 36 You can type normal HTML tags in your documentation Doxygen will convert them to their equiv alent RTF and man page counterparts automatically Allows references to documentation generated for other projects or another part of the same project in a location independent way Allows inclusion of source code examples that are automatically cross referenced with the documen tation Inclusion of undocumented classes is also supported allowing to quickly learn the structure and interfaces of a large piece of code without looking into the implementation details Allows automatic cross referencing of documented entities with their definition in the source code All source code fragments are syntax highlighted for ease of reading Allows inclusion of function member class definitions in the documentation All options are read from an easy to edit and optionally annotated configuration file Documentation and search engine can be transferred to another location or machine without regen erating the documentation Can cope with large projects easily Although doxygen can be used in any C or C project it was specifically des
18. post 22 39 subsection 22 57 22 87 pre 22 40 test 22 46 22 86 ref 22 55 throw 22 47 relates 2219 todo 2248 amp s remarks 22 41 typedef 22 22 lt 22 91 return 22 42 union 22 23 gt 22 92 retval 22 43 until 22 63 22 90 The following subsections provide a list of all commands that are recognized by doxygen Unrecognized commands are treated as normal text Structural indicators 22 1 addtogroup lt name gt title Defines a group just like defgroup but in contrast to that command using the same lt name gt more than once will not result in a warning but rather one group with a merged documentation and the first title found in any of the commands The title is optional so this command can also be used to add a number of entities to an existing group using and like this addtogroup mygrp Additional documentation for group mygrp xf pe A function void funcl User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 67 22 2 class lt name gt lt header file gt lt header name gt Another function void func2 See also page Grouping sections defgroup ingroup and weakgroup 22 2 class lt name gt lt header file gt lt header name gt Indicates that a comment block contains documentation for a class with name lt name gt Optionally a header file and a header name
19. to correct the links Note Each tag file must have a unique name where the name does not include the path If a tag file is not located in the directory in which doxygen is run you must also specify the path to the tagfile here ERATE TAGFILE When a file name is specified after GENERATE TAGFILE doxygen will create a tag file that is based on the input files it reads See section Doxytag usage for more information about the usage of tag file ALL EXTERNALS If the ALLE S XTERNALS tag is set to YES all external class will be listed in the class PERL PATH The Pi index If set to NO only the inherited external classes will be listed result of which perl 21 12 Dot options HAVI E DOT If you set the HAV ERL_PATH should be the absolute path and name of the perl script interpreter i e the F_DOT tag to Y ES then doxygen will assume the dot tool is available from the path This tool is part of Graphviz a graph visualization toolkit from AT amp T and Lucent Bell Labs The other options in this section have no effect if this option is set to NO the default CLASS_GRAPH If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen will generate a graph for each documented class showing the direct and indirect inheritance relations Setting this tag to YES will force the the CLASS_DIAGRAMS tag to NO User Manual for Do
20. For more info see section ref page2 subsection subsectionl The first subsection Text subsection subsection2 The second subsection More text page page2 Another page Even more info 7 Note The lt name gt argument consists of a combination of letters and number digits If you wish to use upper case letters e g 1 or mixed case letters e g MyPage1 in the lt name gt argument you should set CASE_LSENSE_NAMES to YES However this is advisable only if your file system is case sensitive Otherwise and for better portability you should use all lower case letters e g mypage1 for lt name gt in all references to the page See also section section section subsection and section ref 22 19 relates lt name gt This command can be used in the documentation of a non member function lt name gt It puts the function inside the related function section of the class documentation This command is useful for documenting non friend functions that are nevertheless strongly coupled to a certain class It prevents the need of having to document a file but only works for functions Example User Manual for Doxygen 1 2 8 1 written by Dimitri Heesch 1997 2001 22 20 showinitializer A String class xy class String friend int strcmp const String amp const String amp Compares two strings int strcmp const String am
21. HTML output This character has to be escaped because it has a special meaning in HTML 22 89 This command writes the character to the HTML and output This character has to be escaped in some cases because it is used to expand environment variables 2290 This command writes the character to the HTML and TX output This character has to be escaped in some cases because it is used to refer to documented entities 2291 lt This command writes the lt character to the HTML IEX output This character has to be escaped because it has a special meaning in HTML 2292 gt This command writes the gt character to the HTML and IZTEX output This character has to be escaped because it has a special meaning in HTML Commands included for Qt compatibility The following commands are supported to remain compatible to the Qt class browser generator Do not use these commands in your own documentation annotatedclasslist classhierarchy define functionindex header headerfilelist inherit l postheader User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 93 23 HTML Commands Here is a list of all HTML commands that may be used inside the documentation Note that all attributes of a HTML tag are ignored the HREF and NAME attributes for the A tag are the only exception lt A lt A lt B lt lt B lt lt B C C D AAAAA
22. HTML H gt Where is one of 3 4 5 6 ends an unnumbered subsubsection using lt H3 gt in HTML gt Starts a piece of text displayed in an italic font NPUT gt Does not generate any output I Ends a lt I gt section G gt This command is written with attributes to the HTML output only I gt Starts a new list item LI Ends a list item ETA gt Does not generate any output ULTICOL gt ignored by doxygen UTLICOL gt ignored by doxygen L gt Starts a numbered item list OL gt Ends a numbered item list gt Starts a new paragraph P gt Ends a paragraph RE gt Starts a preformatted fragment E gt Ends a preformatted fragment ALL gt Starts a section of text displayed in a smaller font SMALL gt Ends a lt SMALL gt section TRONG gt Starts a section of bold text STRONG gt Ends a section of bold text D Jj for Doxygen 1 2 8 1 written by Dimitri van Heesch c 1997 2001 94 SUB Starts a piece of text displayed in subscript lt SUB gt Ends a SUB section lt SUP gt Starts a piece of text displayed in superscript lt SUP gt Ends a lt SUP gt section lt TABLE gt starts a table lt TABLE gt ends a table lt TD gt Starts a new table data element lt TD gt Ends a table data element lt TR gt Starts a new table row lt TR gt Ends a table row lt TT gt Starts a piece of text displayed in a typewriter font TT
23. INCLUDE GRAPH 63 INCLUDE PATH 61 INCLUDED B Y GRAPH 63 INHERIT DOCS 53 INLINE_INFO 53 INLINE SOURCES 52 INPUT 55 INPUT_FILTER 56 installation 4 INTERNAL_DOCS 52 JAVADOC_AUTOBRIEF 53 LaTeX 12 LATEX_BATCHMODE 59 LATEX HEADER 59 LATEX_OUTPUT 59 license 1 MACRO EXPANSION 61 make 4 MAN LINKS 61 MAN_OUTPUT 60 MAX_DOT GRAPH HEIGHT 63 MAX DOT GRAPH WIDTH 63 MAX_EXTENSION 61 MAX INITIALIZER LINES 54 OPTIMIZE_OUTPUT_FOR_C 54 output formats 44 OUTPUT DIRECTORY 51 OUTPUT_LANGUAGE 51 PAPER_TYPE 59 parsing 12 PDF_HYPERLINKS 59 perl 4 PERL_PATH 62 PREDEFINED 61 PROJECT_NAME 51 PROJECT_NUMBER 51 Qt 4 QUIET 54 RECURSIVE 55 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 INDEX REPEAT BRIEF 52 RTF_HYPERLINKS 60 RTF_OUTPUT 60 RTF STYLESHEET FILE 60 SEARCH INCLUDES 61 SEARCHENGINE 63 SHORT_NAMES 53 SHOW INCLUDE FILES 53 SHOW USED FILES 54 SORT MEMBER DOCS 53 SOURCE BROWSER 52 STRIP CODE COMMENTS 52 STRIP_FROM PATH 52 TAB SIZE 53 TAGFILES 62 TOC EXPAND 58 TREEVIEW _WIDTH 58 VERBATIM HEADERS 53 WARN_ FORMAT 55 WARN_IF_UNDOCUMENTED 55 WARN LOGFILE 55 WARNINGS 55 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 100
24. IO IO IO IO IO For the Qt 2 1 sources I recommand to use the following settings PROJECT NAME Qt PROJECT NUMBER 2 1 HIDE UNDOC MEMBERS YES HIDE UNDOC CLASSES YES SOURCE BROWSER YES INPUT QTDIR src FILE PATTERNS cpp h q doc RECURSIVE YES EXCLUDE_PATTERNS codec cpp moc_ compat 3rdparty ALPHABETICAL INDEX YES COLS_IN_ALPHA_INDEX 3 IGNORE_PREFIX Q ENABLE_PREPROCESSING YES MACRO_EXPANSION YES INCLUDE_PATH QTDIR include PREDEFINED Q PROPERTY Q_OVERRIDE Q EXPORT Q ENUMS x OT STATIC CONST static const WS X11 INCLUDE MENUITEM DEF EXPAND ONLY PREDEF YES EXPAND 5 DEFINED Q OBJECT FAKE Q OBJECT ACTIVATE SIGNAL WITH PARAM Q VARIANT AS User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 Here doxygen s preprocessor is used to substitute some macro names that are normally substituted by the C preprocessor but without doing full macro expansion 22 Special Commands 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 Some commands have one or more arguments Each argument has a certain range e If lt sharp gt braces are used the argument is a single word e If round braces are used the argument extends until the end of the line
25. NO non of my functions are shown in the documentation In order for global functions variables enums typedefs and defines to be documented you should document the file in which these commands are located using a comment block containing a file or file command Alternatively you can put all members in a group or module using the ingroup command and then document the group using a comment block containing the defgroup command 4 How can I make doxygen ignore some code fragment You can use Doxygen s preprocessor for this If you put ifndef DOXYGEN_SHOULD_SKIP_THIS code that must be skipped by Doxygen endif DOXYGEN_SHOULD_SKIP_THIS around the blocks that should be hidden and put PREDEFINED DOXYGEN_SHOULD_SKIP_THIS in the config file then all blocks should be skipped by Doxygen as long as PREPROCESSING YES 5 How can I change what is after the include in the class documentation You can document your class like Nclass MyClassName include h path include h Docs for MyClassName To make doxygen put include lt path include h gt in the documentation of the class MyClassName regardless of the name of the actual header file in which the definition of MyClassName is contained If you want doxygen to show that the include file should be included using brackets you should type class MyClassName include h path include h Docs for MyClassName 6 H
26. Test funclInGroupl void Test func2InGroupl name Group2 Description of group 2 8t Function 2 in group 2 Details void Test func2InGroup2 Function 1 in group 2 Details void Test funclInGroup2 8 file docs for this file 8t one description for all members of this group because DISTRIBUTE GROUP DOC is YES in the config file define A 1 define B 2 void glob func 8 Here Group is displayed as a subsection of the Public Members And Group2 is a separate section because it contains members with different protection levels i e public and protected 6 Including formulas Doxygen allows you to put IMEX formulas in the output this works only for the HTML IMEX output not for the RTF nor for the man page output To be able to include formulas as images in the HTML documentation you will also need to have the following tools installed User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 24 25 e latex the compiler needed to parse the formulas To test I have used the teTeX 0 9 distri bution e dvips a tool to convert DVI files to PostScript files I have used version 5 86 from Radical Eye software for testing e gs the GhostScript interpreter for converting PostScript files to bitmaps I have used Aladdin GhostScript 5 10 for testing There are two ways to include formulas in the documentation
27. alent to pasting the file in the documentation and placing htmlonly and endhtmlonly commands around it Files or directories that doxygen should look for can be specified using the EXAMPLE PATH tag of doxy gen s configuration file Commands for visual enhancements User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 66 Na word 87 22 66 Na lt word gt Displays the argument lt word gt using a special font Use this command to refer to member arguments in the running text Example the a x and a y coordinates are used to This will result in the following text the x and y coordinates are used to 22 67 arg item description This command has one argument that continues until the first blank line or until another arg is encountered The command can be used to generate a simple not nested list of arguments Each argument should start with a arg command Example Typing arg c AlignLeft left alignment arg c AlignCenter center alignment arg c AlignRight right alignment No other types of alignment are supported will result in the following text e AlignLeft left alignment e AlignCenter center alignment e AlignRight right alignment No other types of alignment are supported Note For nested lists HTML commands should be used Equivalent to Mi 22 68 Wb word Displays the argument word using bold font Equivalent to b word b
28. application jpg image latex application eps My application width 10cm And this is example of how the relevant part of the configuration file may look IMAGE_PATH my_image_dir Warning The image format for HTML is limited to what your browser supports For IEX the image format must be Encapsulated PostScript eps Doxygen does not check if the image is in the correct format So you have to make sure this is the case 22 82 Matexonly Starts a block of text that will be verbatim included in the generated documentation only The block ends with a endlatexonly command This command can be used to include code that is too complex for doxygen i e images formu las special characters You can use the htmlonly and endhtmlonly pair to provide a proper HTML alternative Note environment variables like HOME are resolved inside a IATEX only block See also section latexonly and section htmlonly 22 83 Wi item description This command has one argument that continues until the first blank line or until another Mi is encountered The command can be used to generate a simple not nested list of arguments Each argument should start with a li command Example Typing li c AlignLeft left alignment li c AlignCenter center alignment li c AlignRight right alignment No other types of alignment are supported will result in the following text User Manual for Doxygen 1 2 8 1 wr
29. 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 with the g option doxygen g config file where lt config file gt is the name of the configuration file If you omit the file name a file named Doxy file will be created If a file with the name config file already exists doxygen will rename it to lt config file gt 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 st din 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 You can probably leave the values of most tags in a generated template configuration file to their default value The INPUT tag is the only tag for which you are required to provide a value See section Configuration for more details about the configuration file For a small project consisting of a few C and or C source and header files you can add the names of the files after the INPUT tag If you have a larger project consisting of a source directory or tree this may become tiresome In this case you should put the root directory or directories after the INPUT tag and add one or more file p
30. blocks that consist of multiple source and header files For a line by line description of a source files use the dontinclude command in combination with the line skip skipline and until commands See also section example and dontinclude 22 60 Mine pattern This command searches line by line through the example that was last included using include or dontinclude until it finds a non blank line If that line contains the specified pattern it is written to the output The internal pointer that is used to keep track of the current line in the example is set to the start of the line following the non blank line that was found or to the end of the example if no such line could be found See section dontinclude for an example 22 61 skip pattern This command searches line by line through the example that was last included using include or dontinclude until it finds a line that contains the specified pattern The internal pointer that is used to keep track of the current line in the example is set to the start of the line that contains the specified pattern or to the end of the example if the pattern could not be found See section dontinclude for an example User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 62 skipline pattern 86 22 62 skipline pattern This command searches line by line through the example that was last included using include or dontinclude until
31. command ends when a blank line or some other sectioning command is encountered See section author for an example 22 30 date date description Starts a paragraph where one or more dates may be entered The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent date commands will be joined into a single paragraph Each date description will start on a new line Alternatively one date command may mention several dates The date command ends when a blank line or some other sectioning command is encountered See section author for an example User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 77 22 31 deprecated description 78 22 31 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 22 32 endif Ends a conditional section that was started with if For each if one and only one matching endif must follow See also if 22 33 exception lt exception object gt exception description Starts an exception description for an exception object with name lt exception object gt Followed by a description of the exception The existence of the exception object is not checked The text of the paragraph has no special internal structure All visua
32. configuration time Currently version unknown 23 languages are supported sorted alphabetically Brazilian Portuguese Chinese Croatian Czech Danish Dutch English Finnish French German Hungarian Italian Japanese Korean Norwegian Polish Portuguese Romanian Russian Slovak Slovene Spanish and Swedish The table of information related to the supported languages follows It is sorted by language alphabeti cally The Status column was generated from sources and shows approximately the last version when the translator was updated User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 95 Contact address Fabio FJTC Jun Takada Chino chino grad icmc sc usp br Wang Weihan wangweihan capinfo com cn poris bralo 2g tel hr up to date Czech Petr P ikryl prikrylp skil cz up to date Dutch German Jens Seidel jensseidel users sourceforge net up to date m Veblen Italian Ahmed Aldo Faisal aaf23 cam ac uk 1 2 7 5 Swedish Samuel H agglund sahag96 nts mh se 1 0 0 XeT Erixon xet hem passagen se Have a look at doxygen doc translator_report txt for more details Most people on the list have indicated that they were also busy doing other things so if you want to help to speed things up please let them or me know If you want to add support for a language that is not yet listed please see the next section Adding a new language to doxygen This sh
33. 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 Structural commands to learn more about structural commands Files can only be documented using the second option The text inside a special documentation block is parsed before it is written to the HTML and or IATEX output files During parsing the following steps take place e The special commands inside the documentation are executed See section Special Commands for an overview of all commands e If a line starts with some whitespace followed by one or more asterixes then the whitespace and asterixes are removed User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 12 13 e All resulting blank lines are treated as a paragraph separators This saves you from placing new paragraph commands yourself in order to make the generated documentation readable e Links are created for words corresponding to documented classes e 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 e HTML tags that are in the documentation are interpreted and converted to IZTEX equivalents for the IATE
34. doxygen use Qt The most important reason is to have a platform abstraction for most Unices and Windows by means of the QFile QFileInfo QDir QDate QTime and QIODevice classes Another reason is for the nice and bug free utility classes like QList QDict QString QArray QTextStream QRegExp QXML etc The GUI front end doxywizard uses Qt for well the GUI 10 How can I exclude all test directories from my directory tree Simply put an exclude pattern like this in the configuration file EXCLUDE_PATTERNS test 11 Doxygen automatically generates a link to the class MyClass somewhere in the running text How do I prevent that at a certain place Put a in front of the class name Like this MyClass Doxygen will then remove the and keep the word unlinked 12 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 rules that matches more than 16K input character in one go I ve seen this happening on a very large generated file gt 16K lines where the built in preprocessor converted it into an empty file with gt 16K of newlines Another case where this might happen is if you have lines in your code with more than 16K characters 11 Troubleshooting Known problems e 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 Use
35. example mainpage My Personal Index Page section intro Introduction This is the introduction section install Installation subsection stepl Step 1 Opening the box UG See also section section section subsection and section page User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 14 name header 73 22 14 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 22 15 namespace lt name gt Indicates that a comment block contains documentation for a namespace with name name 22 16 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 22 17 overload function declaration This command can be used to generate the following standard text for an overloaded member function This is an overloaded member function provided for convenience It differs from the above function only in what argument s it accepts If the documentation for the overloaded member function is not located in front of the function declaration or definition the optional argument should be used to specify the correct function
36. file Always try to include the following information in your bug report e The version of doxygen you are using for instance 1 2 4 e The name and version number of your operating system for instance SuSE Linux 6 4 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 34 It is usually a good idea to send along the configuation file as well but please use doxygen with the s flag while generating it to keep it small The easiest way for me to solve bugs is if you can send me a small example demonstrating the problem you have Please make sure the example is valid source code could potentially compile and that the problem is really captured by the example I often get examples that do not trigger the actual bug If you send only a vague description of a bug you are usually not very helpful and will costs me much more time to figure out what you mean In the worst case your bug report may even be completely ignored by me My e mail address dimitri stack nl 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 e Supports C Java Corba Microsoft and KDE DCOP Java IDL and C sources e Supports documentation of files namespaces classes structs unions templates variables func tions typedefs enums and de
37. file command will belong to the file it is located in Important The documentation of global functions variables typedefs and enums will only be included in the output if the file they are in is documented as well Example file file h A brief file description A more elaborated file description User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 8 fn function declaration A global integer value More details about this value extern int globalValue 22 8 fn function declaration Indicates that a comment block contains documentation for a function either global or as a member of a class This command is needed if a comment block is not placed in front of the function declaration or definition If your comment block is in front of the function declaration or definition this command can and to avoid redundancy should be ommitted A full function declaration should be specified after the fn command The argument ends at the end of the line Example class Test public const char member char int throw std out_of_range const char Test member char throw std out_of_range class Test brief Test class Details about Test N n const char Test member char c int n brief A member function param c a character param n an integer exception std out of range parameter is out o
38. included in the documentation are replaced by links for instance when using SOURCE BROWSER YES This also holds for the Referenced by list that is generated for each function For a part this is because the code parser isn t smart enough at the moment I ll try to improve this in the future But even with these improvements not everthing can be properly linked to the corre sponding documentation because of possible ambiguities or lack of information about the context in which the code fragment is found e It is not possible to insert a non member function f in a class A using the relates command if class A already has a member with name f and the same argument list e There is only very limited support for member specialization at the moment It only works if there is a specialized template class as well e Not all special commands are properly translated to RTF How to help The development of Doxygen highly depends on your input If you are trying Doxygen let me know what you think of it do you miss certain features Even if you decide not to use it please let me know why How to report a bug I would appreciate an e mail if you have found a bug or if you have ideas or even better some code or a patch how to fix existing bugs and limitations For patches please use diff u 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
39. it finds a line that contains the specified pattern It then writes the line to the output The internal pointer that is used to keep track of the current line in the example is set to the start of the line following the line that is written or to the end of the example if the pattern could not be found Note The command skipline pattern is equivalent to skip pattern line pattern See section dontinclude for an example 22 63 until pattern This command writes all lines of the example that was last included using include or dontinclude to the output until it finds a line containing the specified pattern The line containing the pattern will be written as well The internal pointer that is used to keep track of the current line in the example is set to the start of the line following last written line or to the end of the example if the pattern could not be found See section dontinclude for an example 22 64 verbinclude lt file name gt This command includes the file lt file name gt verbatim in the documentation The command is equivalent to pasting the file in the documentation and placing verbatim and endverbatim commands around it Files or directories that doxygen should look for can be specified using the EXAMPLE PATH tag of doxy gen s configuration file 22 65 htmlinclude lt file name gt This command includes the file lt file name gt as is in the HTML documentation The command is equiv
40. li gt key up event lt ol gt lt ul gt More text here F XX F Note The the indent 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 not nested 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 20 5 1 Modules 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 y
41. on which the command was found e If curly braces are used the argument extends until the next paragraph Paragraphs are delimited by a blank line or by a section indicator If square brackets are used the argument is optional Here is an alphabetically sorted list of all commands with references to their documentation a 22 66 dontinclude 22 58 hideinitializer 22 9 addindex 22 51 e 22 71 htmlinclude 22 65 addtogroup 22 1 em 22 72 htmlonly 22 80 anchor 22 52 endcode 22 73 if 22 34 arg 22 67 endhtmlonly 22 74 image 22 81 attention 22 26 endif 22 32 include 22 59 author 22 27 endlatexonly 22 15 ingroup 22 10 b 22 68 endlink 22 53 internal 22 12 brief 22 28 endverbatim 22 76 invariant 22 35 bug 22 29 enum 22 5 interface 22 11 c 22 69 example 22 6 latexonly 22 82 class 22 2 exception 22 33 li 22 83 code 22 70 MS 22 77 line 22 60 date 22 30 MI 22 78 link 22 54 def 22 3 M 22 79 mainpage 22 13 defgroup 22 4 file 22 7 name 22 14 deprecated 22 31 fn 22 8 namespace 22 15 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 66 221 addtogroup lt name gt title nosubgrouping 22 16 sa 22 44 var 22 24 note 22 36 section 22 56 verbatim 22 85 overload 22 17 showinitializer 22 20 verbinclude 22 64 p 22 84 since 22 45 version 22 49 22 18 ki 22 61 Wage usb warning 22 50 par 22 37 skipline 22 62 weakgroup 22 25 param 22 38 struct 22 21 22 89
42. the class documentation is currently shown e A dark blue arrow indicates an include relation for the include dependency graph or public inher itance for the other graphs e A dark green arrow indicates protected inheritance e A dark red arrow indicates private inheritance e A purple dashed arrow indicated a usage relation the edge of the arrow is labled with the vari able s responsible for the relation Class A uses class B if class A has a member variable m of type C where is a subtype of C e g C could be B Bx T lt B gt Here are a couple of header files that together show the various diagrams that doxygen can generate diagrams a h User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 26 27 ifndef DIAGRAMS A H define DIAGRAMS A class public A m self diagrams b h ifndef DIAGRAMS B H define DIAGRAMS B H class A class B public A m a diagrams c h ifndef DIAGRAMS C H define DIAGRAMS include diagrams c h class D class C public A public D m d diagrams d h ifndef DIAGRAM D H define DIAGRAM D H include diagrams a h include diagrams b h class Cs class D virtual protected A private B public C m c diagrams e h ifndef DIAGRAM E H define DIAGRAM E H include diagrams d h class E public D
43. the detailed description Note If both HIDE UNDOC MEMBERS and BRIEF _MEMBER _DESC are set to NO the brief descrip tions will be completely suppressed ALWAYS DETAILED SEC If the ALWAYS DETAILED SEC and REPEAT_BRIEF tags are both set to YES then doxygen will generate a detailed section even if there is only a brief description FULL PATH NAMES If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path before files name in the file list and in the header files If set to NO the shortest path that makes the file name unique will be used STRIP FROM PATH Ifthe 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 CLASS_DIAGRAMS If the CLASS_DIAGRAMS tag is set to YES the default doxygen will generate a class diagram in HTML IZTEX for classes with base or super classes Setting the tag to NO turns the diagrams off SOURCE_BROWSER If the SOURCE BROWSER tag is set to YES then a list of source fi
44. 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 20 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
45. the paragraph Multiple adjacent invariant commands will be joined into a single paragraph Each invariant description will start on a new line Alternatively one invariant command may mention several invariants The invariant command ends when a blank line or some other sectioning command is encountered 22 36 note text Starts a paragraph where a note can be entered The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent note commands will be joined into a single paragraph Each note description will start on a new line Alternatively one note command may mention several notes The note command ends when a blank line or some other sectioning command is encountered See section par for an example 22 37 par paragraph title paragraph If a paragraph title is given this command starts a paragraph with a user defined heading The heading extends until the end of the line The paragraph following the command will be indented If no paragraph title is given this command will start a new paragraph This will also work inside other paragraph commands like param or warning without ending the that command The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph The par command ends when a blank line or some other sectioning command is enco
46. was started with a htmlonly command See also section htmlonly 22 75 endlatexonly Ends a block of text that was started with a latexonly command See also section latexonly 22 76 endverbatim Ends a block of text that was started with a verbatim command See also section verbatim 2277 f Marks the start and end of an in text formula See also section formulas for an example User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 89 2278 AVI 90 2278 MI Marks the start of a long formula that is displayed centered on a separate line See also section M and section formulas 22 79 Wf Marks the end of a long formula that is displayed centered on a separate line See also section MT and section formulas 22 80 htmlonly Starts a block of text that will be verbatim included in the generated HTML documentation only The block ends with a endhtmlonly command This command can be used to include HTML code that is too complex for doxygen i e applets java scripts and HTML tags that require attributes You can use the latexonly and endlatexonly pair to provide a proper IATEX alternative Note environment variables like HOME are resolved inside a HTML only block See also section htmlonly and section Matexonly 22 81 image lt format gt lt file gt lt caption gt lt sizeindication gt lt size gt Inserts an image into the document
47. will be put under the same header in the alphabetical index The IGNORE_PREF IX tag can be used to specify a prefix or a list of prefixes that should be ignored while generating the index headers 21 6 HTML related options GENERATE_HTML If the GENERATE_HTML tag is set to YES the default doxygen will generate HTML output User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 6 HTML related options 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 HEADER 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 lt HTML gt and a lt BODY gt tag but it is good idea to include the style sheet that is generated by doxygen as well Minimal example lt HTML gt lt HEAD gt lt TITLE gt My title lt TITLE gt lt LINK HREF doxygen css REL stylesheet TYPE text css gt lt HEAD gt lt BODY BGCOLOR FFFFFE gt If the tag is left blank doxygen will generate a standard header The following commands have a special meaning inside the header Stitle datetime Sdate Sdoxygenversion Sprojectname projectnumber Doxygen will replace them by re
48. 2 protected int var lt A member variable details Test Test details Test Test A global variable int globVar A global enum enum GlobEnum GVall global enum value 1 GVal2 global enum value 2 peel A macro definition af define ABS x gt 0 typedef Test B fn typedef Test B A type definition wy User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 20 6 typedefs 20 6 typedefs Typedefs that involve classes structs and unions like 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 E 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 Jel This function returns the addition of a cl and a c2 i e eT zte x eI yte y E 1 c2 21 Configuration 21 1 Format A configuration file is a free form ASCII text file with a structure that is similar to that of a Makefile It is parsed by doxygen The file may contain tabs and newlines for formatting purposes
49. 97 bison simple Mon Jan 26 15 10 26 1998 27 7 27 7 ifdef GNUC__ define alloca __builtin_alloca 1 not GNU C include alloca h else not sparc if defined MSDOS amp amp defined __TURBOC__ if defined __STDC__ amp amp defined sparc defined __sparc__ if defined __STDC__ amp amp defined sparc defined __sparc__ The generated scanner cpp that comes with doxygen is build with this patch applied Sun compiler problems defined defined __sparc __ sparc 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 __sparc sparc defined _ defined _ defined __sc defined __sc QOList PageInfo vtbl home dimitri doxygen objects SunWS cache CC obj 6 6c3eO410gMT2vrlGCQUQ o Hint try checking whether the first non inlined non pure virtual function of class QList PageInfo is These are generated because the compiler is confused about the object sharing between doxygen and doxytag To compile doxytag and doxysearch anyway do rm rf objects mkdir objects cd sre gmake f Makefile doxytag gmake f Makefile doxysearch User Manual for Doxygen 1 2 8 1 written by D
50. AAAA D D D lt F lt lt H lt H lt lt H lt lt H lt I I lt I lt L lt lt M lt o P lt lt P lt s lt S User Manual MI E HREF gt Starts a HTML hyper link HTML only NAME Starts an named anchor HTML only lt A gt Ends a link or anchor HTML only gt Starts a piece of text displayed in a bold font B Ends a lt B gt section ODY gt Does not generate any output BODY Does not generate any output R gt Forces a line break ENTER starts a section of centered text CENTER ends a section of centered text D ODE Starts a piece of text displayed in a typewriter font CODE End a lt CODE gt section D gt Starts an item description FN Starts a piece of text displayed in a typewriter font DFN Ends a lt DFN gt section L2 Starts a description list L gt Ends a description list T gt Starts an item title DT gt Ends an item title gt Starts a piece of text displayed in an italic font EM gt Ends a lt EM gt section ORM gt Does not generate any output FORM gt Does not generate any output R gt Writes a horizontal ruler 1 gt Starts an unnumbered section H1 gt Ends an unnumberd section 2 gt Starts an unnumbered subsection H2 gt Ends an unnumbered subsection Where is one of 3 4 5 6 starts an unnumbered subsubsection using lt H3 gt in
51. Any other documentation that is inside the documentation block will by appended after the generated message Note 1 You are responsible that there is indeed an earlier documented member that is overloaded by this one To prevent that document reorders the documentation you should set SORT MEMBER DOCS to NO in this case Note 2 The Voverload command does not work inside a one line comment Example class Test public void drawRect int int int int void drawRect const Rect amp r 1 void Test drawRect int x int y int w int h void Test drawRect const Rect amp r class Test brief A short description User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 18 page lt name gt title 74 More text fn void Test drawRect int x int y int w int h This command draws a rectangle with a left upper corner at Na x a y width w and height h 7 4 Noverload void Test drawRect const Rect amp r 22 18 page lt name gt title Indicates that a comment block contains a piece of documentation that is not directly related to one specific class file or member The HTML generator creates a page containing the documentation The IATEX generator starts a new section in the chapter Page documentation Example page pagel A documentation page This page contains the subsections ref subsectionl and ref subsection2
52. DOT to YES in the configuration file to let doxygen use it Doxygen uses the dot tool to generate the following graphs User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 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 if CLASS_GRAPH is set to YES a graph will be generated for each documented class showing the direct and indirect inheritance relations This disables the generation of the build in class inheritance diagrams if INCLUDE_GRAPH is set to YES an include dependency graph is generated for each documented file that includes at least one other file This feature is currently supported for HTML and RTF only if COLLABORATION is set to YES a graph is drawn for each documented class and struct that shows the inheritance relations with base classes the usage relations with other structs amp classes e g class A has a member variable m_a of type class B then A has an arrow to B with m_a as label The elements in the class diagrams in HTML and RTF have the following meaning A yellow box indicates a class A box can have a little marker in the lower right corner to indicat
53. GUI Toolkit which is very useful as a Win dows Unix platform abstraction layer My brother Frank for rendering the logos Harm van der Heijden for adding HTML help support Wouter Slegers for registering the www doxygen org domain Parker Waerchter 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 Ken Wong for providing the HTML tree view code User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 CONTENTS Jens Breitenstein Christophe Bordeaux Samuel H gglund Xet Erixon Vlastimil Havran Petr Prikryl Ahmed Also Faisal Alessandro Falappa Kenji Nagamatsu Francisco Oltra Thennet Olli Korhonen Boris Bralo Nickolay Semyonov Richard Kim F ldvari Gy rgy Grzegorz Kowal and Wang Weihan for providing translations into various languages The Comms group of Symbian for donating me an ultra cool Revo plus organizer 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 2 8 1 written by Dimitri van Heesch 1997 2001 Part I User Manual 1 Installation First go to the download page http www stack nl dimitri doxygen download html to get the latest distribution if y
54. If doxytag is used with the t flag it generates a tag file Example 1 Suppose the file example cpp from the examples directory that is listed below is included in some package for which you do not have the sources Fortunately the distributor of the packages included the HTML documentation that was generated by doxygen in the package A Test class More details about this class class Test public An example member function More details about this function void example void Test example 1 example example test cpp This is an example of how to use the Test class More details about this example Now you can create a tag file from the HTML files in the package by typing doxytag t example tag example html from the examples directory Finally you can use this tag file with your own piece of code such as done in the following example A class that is inherited from the external class Test y class Tag public Test public an overloaded member void example Doxygen will now include links to the external package in your own documentation Because tag file does not specify where the documentation is located you will have to specify that by running the installdox script that doxygen generates See section Installdox usage for more information Note that this is actually a feature because if you or someone else moves the external documen
55. If you have success with other programs please let me know 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 IEX output by running make ps in the output directory For the best results PDF HYPERLINKS should be set to NO PDF Generated from the IEX 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 20 Automatic link generation Most documentation systems have special see also sections where links to other pieces of documentation can be inserted Although doxygen also has a command to start such a section See section sa it does allow you to put these kind of links anywhere in the documentation For IATEX documentation a reference to the page number is written instead of a link Furthermore the index at the end of the document can be User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 44 20 1 Links to web pages and mail addresses 45 used to quickly find the documentation of a member class namespace or file For man pages no reference information is generated The next sections show how to generate links to the various documented entities in a source file 20 1 Links to web pa
56. LE using doxygen w rtf rtfstyle cfg If you do not want documentation for each item inside the configuration file then you can use the optional s option This can use be used in combination with the u option to add or strip the documentation from an existing configuration file Please use the s option if you send me a con figuration file as part of a bug report To make doxygen read write to standard input output instead of from to a file use for the file name 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 can generate tag files These tag files can be used with doxygen to generate references to external documentation i e documentation not contained in the input files that are used by doxygen A tag file contains information about files classes and members documented in external documen tation Doxytag extracts this information directly from the HTML files This has the advantage that you do not need to have the sources from which the documentation was extracted If you do have the sources it is better to let doxygen generate the tag file by putting the name of the tag file after GENERATE TAGFILE in the configuration file 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
57. Man page format User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 2 3 Step 3 Documenting the sources 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 ht m1 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 IKIEX documentation must first be compiled by IEX compiler I use teTeX distribu tion version 0 9 that contains 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 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_2onl 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 ghos
58. The statements in the file are case sensitive Comments may be placed anywhere within the file except within quotes Comments begin with the character and end at the end of the line Gl The file essentially consists of a list of assignment statements Each statement consists of a TAG_NAMI written in capitals followed by the character and one or more values If the same tag is assigned more than once the last assignment overwrites any earlier assignment For options that take a list as their argument the operator can be used instead of to append new values to the list Values are sequences User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 48 21 1 Format of non blanks If the value should contain one or more blanks it must be surrounded by quotes 7 Multiple lines can be concatenated by inserting a backslash V as the last character of a line Environment variables can be expanded using the pattern 5 ENV VARIABLE NAME You can also include part of a configuration file from another configuration file using a INCLUDE tag as follows INCLUDE config file name The include file is searched in the current working directory You can also specify a list of directories that should be searched before looking in the current working directory Do this by putting a INCLUDE_PATH tag with these paths before the INCLUDE tag e g QGINCLUDE PATH my config dir The config
59. X output See section HTML Commands for an overview of all supported HTML tags 3 Documenting the code 3 1 Special documentation blocks The following types of special documentation blocks are supported by doxygen e The Qt style where special documentation blocks look like pe text and the one line version IY ONS Vine of text 222 e The JavaDoc style where special documentation blocks look like 25 and the one line version one line of text Doxygen only allows one brief and one detailed description If there is one brief description before a declaration and one before a definition 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 A test class LEI A more elaborate class description 5 class Test public An enum More detailed enum description enum TEnum TVall lt Enum value TVall TVal2 lt Enum value TVal2 TVa13 lt Enum value TVal3 Enum pointer User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 3 1 Special documentation blocks Details enumPtr Enum variable Details enumVar A constructor more el
60. a graph becomes larger than this value doxygen will try to truncate the graph so that it fits within the specified constraint Beware that most browsers cannot cope with very large images MAX DOT GRAPH WIDTH MAX DOT GRAPH WIDTH tag can be used to set the maximum allowed width in pixels of the graphs generated by dot If a graph becomes larger than this value doxygen will try to truncate the graph so that it fits within the specified constraint Beware that most browsers cannot cope with very large images GENERATE LEGEND If the GENERATE_LEGEND tag is set to YES the default doxygen will generate a legend page explaining the meaning of the various boxes and arrows in the dot generated graphs 21 13 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 CGI_NAME tag should be the name of the CGI script that starts the search engine 4 search with the correct parameters A script with this name will be generated by doxygen User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 13 Search engine options CGI_URL The CGI_URL tag should be the absolute URL to the directory where the cgi binaries are located See the documentation of yo
61. aborate description of the constructor Test A destructor A more elaborate description of the destructor x Test A normal member taking two arguments and returning an integer value fe param a an integer argument param s a constant character pointer return The test results sa Test Test testMeToo and publicVar S int testMe int a const char s A pure virtual member fe sa testMe param cl the first argument param c2 the second argument virtual void testMeToo char cl char c2 0 A public variable Les Details int publicVar A function variable Pe Details int handler int a int b 1 The one line comments should contain a brief description whereas the multi line comment blocks contain a more detailed description Note that consecutive one line comments are merged together in one brief 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 descrip tions 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 documen
62. also section Doxygen usage for information on how to generate the style sheet that doxygen normally uses HTML ALIGN MEMBERS If the HTML ALIGN MEMBERS tag is set to YES the members of classes files or namespaces will be aligned in HTML using tables If set to NO a bullet list will be used Note Setting this tag to NO will become obsolete in the future since I only intent to support and test the aligned representation User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 7 LaTeX related options ERATE HTMLHELP If the GENERATE HTMLHELP tag is set to YES then doxygen generates three additional HTML index files index hhp index hhc and index hhk The in dex hhp is a project file that can be read by Microsoft HTML Help Workshop see http msdn microsoft com library tools htmlhelp wkshp download main htm 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
63. an Heesch 1997 2001 17 43 cp search cgi usr local lib httpd cgi bin Create a text file with the name search cfg On the first line you must put the absolute URL to the Qt documentation Since I only use the search engine on my own standalone system I use the file protocol On the second line you must put the absolute URL to the cgi script On my system the resulting file looks like this file usr local qt html http blizzard cgi bin search cgi Add a link to the search engine in the Qt documentation On my system I have put a line lt li gt lt a href http blizzard cgi bin search cgi gt Search the documentation lt a gt in the additional information section of the index html file 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 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 one for each section in the configuration file Each tab field contains a number of lines one for each configuration option in that section The kind of input widget depends on the type of the configuration option 18 For each boolean option those options that are answered with YES or NO in the configuration file there is a check box For items
64. aragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent version commands will be joined into a single paragraph Each version description will start on a new line Alternatively one version command may mention several version strings The version command ends when a blank line or some other sectioning command is encountered See section author for an example 22 50 warning warning message Starts a paragraph where one or more warning messages may be entered The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent warning commands will be joined into a single paragraph Each warning description will start on a new line Alternatively one warning command may mention several warnings The warning command ends when a blank line or some other sectioning command is encountered See section author for an example Commands to create links 22 51 addindex text This command adds text to the IATEX index 22 52 anchor lt word gt This command places an invisible named anchor into the documentation to which you can refer with the ref command See also section ref User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 82 22 53 endlink 83 22 53 endlink This command ends a link that is started with the l
65. ation This command is format specific so if you want to insert an image for more than one format you ll have to repeat this command for each format The first argument specifies the output format Currently the following values are supported html and latex The second argument specifies the file name of the image doxygen will look for files in the paths or files that you specified after the IMAGE_PATH tag If the image is found it will be copied to the correct output directory If the image name contains spaces you ll have to put quotes around it You can also specify an absolute URL instead of a file name but then doxygen does not copy the image nor check its existance The third argument is optional and can be used to specify the caption that is displayed below the image This argument has to be specified between quotes even if it does not contain any spaces The quotes are stripped before the caption is displayed The fourth argument is also optional and can be used to specify the width or height of the image This is only useful for output i e format latex The sizeindication can be either width or User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 82 latexonly 91 height The size should be a valid size specifier in for example 10cm or or a symbolic width like textwidth Here is example of a comment block Here is a snapshot of my new application image html
66. ation as compactly as possible the size of the index is still quite large Usually it is about the same size as the original HTML files Ihave tried to make the search engine highly portable because it must run on the target system As a result doxysearch does not require the Qt library All that is required to build doxysearch is a C compiler If you are using g for example you can build the search engine manually by typing g doxysearch cpp o doxysearch 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 e A small shell script The name of the script is determined by the CGI_NAME tag in the configu ration 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 di rectory e search cfg this file is a small configuration file for the search engine It contains two lines of text The first line should be the absolute URL to the documentatio
67. atterns 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 all files will be parsed 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 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 warnings of 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 defini tion 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 handly for code reviews for instance 2 20 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 and Unix
68. can be specified If the header file is specified a link to a verbatim copy of the header will be included in the HTML documentation The lt header name gt argument can be used to overwrite the name of the link that is used in the class documentation to something other than lt header file gt This can be useful if the include name is not located on the default include path like lt X11 X h gt With the lt header name gt argument you can also specify how the include statement should look like by adding either quotes or sharp brackets around the name Sharp brackets are used if just the name is given Example A dummy class class Test Nclass Test class h inc class h brief This is a test class Some details about the Test class 22 3 def lt name gt Indicates that a comment block contains documentation for a define macro Example file define h brief testing defines This is to test the documentation of defines x Lel def MAX x y Computes the maximum of a x and a y y Computes the absolute value of its argument a x define ABS x gt 0 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 68 22 4 defgroup lt name gt group title 69 fdefine gt define gt lt Computes the minimum of x Na y 22 4 defgroup
69. comment block All examples are placed in a list The source code is User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 227 file lt name gt 70 scanned for documented members and classes If any are found the names are cross referenced with the documentation Source files or directories can be specified using the EXAMPLE PATH tag of doxygen s configuration file If lt file name gt itself is not unique for the set of example files specified by the EXAMPLE_PATH tag you can include part of the absolute path to disambiguate it If more that one source file is needed for the example the include command can be used Example A Test class More details about this class class Test public An example member function More details about this function void example void Test example example example_test cpp This is an example of how to use the Test class More details about this example Where the example file example_test cpp looks as follows void main Test t t example See also section include 22 7 file lt name gt Indicates that a comment block contains documentation for a source or header file with name lt name gt The file name may include part of the path if the file name alone is not unique If the file name is omitted Le the line after file is left blank then the documentation block that contains the
70. cument 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 3 2 Structural commands 17 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 NETL oe ora file line in this file Here is an example of a C header named st ruct cmd h that is documented using structural commands Nfile structcmd h brief A Documented file Details Nde brief A macro that returns the maximum of a and b Details n Nvar typedef unsigned int UINT32 brief A type definition for a Details ud Nvar int errno brief Contains the last error code Warning Not thread safe 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 w
71. doc src FILE PATTERNS po th INCLUDE_PATH examples TAGFILES qt tag PERL_PATH usr local bin perl SEARCHENGINE YES CGI_NAME search cgi CGI_URL http www stack nl dimitri cgi bin DOC_URL http www stack nl dimitri qdbttabular DOC_ABSPATH home dimitri html qdbttabular BIN_ABSPATH home dimitri bin To regenerate the Qt 1 44 documentation from the sources you could use the following config file User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 64 21 13 Search engine options PROJECT_NAME Ot OUTPUT_DIRECTORY qt docs HIDE UNDOC MEMBERS YES HIDE UNDOC CLASSES YES ENABLE PREPROCESSING YES MACRO EXPANSION YES EXPAND ONLY PREDEF YES SEARCH INCLUDES YES FULL PATH NAMES YES STRIP FROM PATH QTDIR PREDEFINED USE_TEMPLATECLASS Q_EXPORT QArrayT QArray N QListT QList QDictT QDict QQueueT QQueue QVectorT QVector QPtrDictT QPtrDict ntDictT QIntDict StackT QStack DictIteratorT QDictIterator ListIteratorT QListIterator CacheT QCache CacheIteratorT QCacheIterator N ntCacheT QIntCache ntCachelIteratorT QIntCacheIterator N ntDictIteratorT QIntDictIterator QPtrDictIteratorT QPtrDictIterator INPUT QTDIR doc N QTDIR src widgets N QTDIR src kernel N QTDIR src dialogs N QTDIR src tools FILE PATTERNS cpp h q doc INCLUDE PATH S QTDIR include RECURSIVE YES IO IO IO IO
72. documentation is generated This name is used in the title of most generated pages and in a few other places PROJECT_NUMBER The PROJECT_NUMBER tag can be used to enter a project or revision number This could be handy for archiving the generated documentation or if some version control system is used OUTPUT_DIRECTORY The OUTPUT_DIRECTORY tag is used to specify the relative or absolute path into which the generated documentation will be written If a relative path is entered it will be relative to the location where doxygen was started If left blank the current directory will be used OUTPUT_LANGUAGE The OUTPUT_LANGUAGE tag is used to specify the language in which all docu mentation generated by doxygen is written Doxygen will use this information to generate all con stant output in the proper language The default language is English other supported languages are Dutch French Italian Czech Swedish German Finnish Hungarian Japanese Korean Spanish Russian Croatian Polish and Portuguese EXTRACT_ALL Ifthe EXTRACT_ALL tag is set to YES doxygen will assume all entities in documentation are documented even if no documentation was available Private class members and static file members will be hidden unless the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES Note This will also disable the warnings about undocumented members that are normally produced when WARNINGS is se
73. e output To get the times font for instance you can specify 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 header for the gener ated 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 The following commands have a special meaning inside the header Stitle datetime Sdate Sdoxygenversion projectname projectnumber Doxygen will replace them by respectively the title of the page the current date and time only the current date the version number of doxygen the project name see PROJECT NAME or the project number see PROJECT NUMBER PDF HYPERLINKS Ifthe PDF_HYPERLINKS tag is set to YES the that is generated is prepared for conversion to PDF using ps2pdf The PDF file will contain links just like the HTML output instead of page references This makes the output suitable for online browsing using a PDF viewer LATEX_BATCHMODE If the LATEX BATCHMODE tag is set to YES doxygen will add the batchmode command to the generated files This will instruct IATEX to keep running i
74. e PREDEFINED or EXPAND_AS_DEFINED tag As an example suppose you have the following obfuscated code fragment of an abstract base class called TUnknown A reference to an IID ifdef _ cplusplus define REFIID const IID amp else define REFIID const IID fendif The IUnknown interface DECLARE_INTERFACE IUnknown STDMETHOD HRESULT QueryInterface THIS_ REFIID iid void ppv PURE STDMETHOD ULONG AddRef THIS PURE STDMETHOD ULONG Release THIS PURE 1 without macro expansion doxygen will get confused but we may not want to expand REFIID macro because it is documented and the user that reads the documentation should use it when implementing the interface By setting the following in the config file ENABLE_PREPROCESSING YES MACRO EXPANSION ES EXPAND_ONLY_PREDEF YES PREDEFINED DECLARE INTERFACE name class name STDMETHOD result name virtual result name PURE 0 THIS_ THIS __cplusplus K we can make sure that the proper result is fed to doxygen s parser User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 29 A reference to an IID define REFIID The IUnknown interface class IUnknown virtual HRESULT QueryInterface REFIID iid void ppv 0 virtual ULONG AddRef 0 virtual ULONG Release 0 Note that the PREDEFINED tag accepts function like macro definitions l
75. e that the class contains base classes that are hidden For the class diagrams the maximum tree width is currently 8 elements If a tree is wider some nodes will be hidden If the box is filled with a dashed pattern the inheritance relation is virtual A white box indicates that the documentation of the class is currently shown A grey box indicates an undocumented class A solid dark blue arrow indicates public inheritance A dashed dark green arrow indicates protected inheritance A dotted dark green arrow indicates private inheritance The elements in the class diagram in have the following meaning A white box indicates a class A marker in the lower right corner of the box indicates that the class has base classes that are hidden If the box has a dashed border this indicates virtual inheritance A solid arrow indicates public inheritance A dashed arrow indicates protected inheritance A dotted arrow indicates private inheritance The elements in the graphs generated by the dot tool have the following meaning e A white box indicates a class or struct or file e A box with a red border indicates a node that has more arrows than are shown In other words the graph is truncated with respect to this node The reason why a graph is sometimes truncated is to prevent images from becoming too large For the graphs generated with dot doxygen tries to limit the width of the resulting image to 1024 pixels A black box indicates that
76. e installdox script that is generated by doxygen if you use tag files e Section Output Formats shows how to generate the various output formats supported by doxygen e Section Automatic link generation shows how to put links to files classes and members in the doc umentation Section Configuration shows how to fine tune doxygen so it generates the documentation you want e 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 Section Internationalization explains how to add support for new output languages Projects using doxygen Ihave compiled a list of projects that use doxygen see http www stack nl dimitri doxygen projects ht If you know other projects let me know and add them Future work Although doxygen is used successfully by lot of people already there 15 al ways room for improvement Therefore I have compiled a todo wish list see http www stack nl edimitri doxygen todo html of possible and or requested enhancements 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
77. ember grouping Doxygen now has a GUI front end called doxywizard based on Qt 2 1 All info about configuration options is now concentrated in a new tool called configgen This tool can generate the configuration parser and GUI front end from source templates Better support for the using keyword New transparent mini logo that is put in the footer of all HTML pages Internationalization support for the Polish Portuguese and Croatian language Todo list support User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 37 e If the source browser is enabled for a function a list of function whose implementation calls that function is generated e All source code fragments are now syntax highlighted in the HTML output The colors can be changed using cascading style sheets Version 1 0 0 Major new features e Support for templates and namespaces Internationalization support Currently supported languages are English Czech German Spanish Finnish French Italian Japanese Dutch and Swedish Automatic generation of inheritance diagrams for sub amp super classes Support for man page compressed HTML help and hyperlinked PDF output Cross referencing documentation with source code and source inlining LaTeX formulas can be included in the documentation Support for parsing Corba amp Microsoft IDL Images can be included in the documentation Improved parsing amp preprocessing Version 0 4
78. erived from the input used in their production they are not affected by this license Introduction Doxygen is a documentation system for C Java IDL Corba Microsoft and KDE DCOP flavors and C 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 BIEX 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 documen tation is extracted directly from the sources which makes it much easier to keep the documentation consistent with the source code 2 Doxygen can be configured to extract the code structure from undocumented source files This can be very useful to quickly find your way in large source distributions The relations between the various elements are be visualized 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 an executable for Windows 9x NT is also available This manual is divided into two parts each of which is divided into several sections The first part forms a user manual Section Installation discusses how
79. f 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 events mouse events mouse move event 4 mouse click event n More info about the click event 4 mouse double click event keyboard events key down event key up event More text here F F F HF F The result will be A list of events e mouse events 1 mouse move event 2 mouse click event More info about the click event 3 mouse double click event e keyboard events 1 key down event 2 key up event User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 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 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 A list of events lt ul gt lt li gt mouse events lt ol gt lt li gt mouse move event lt li gt mouse click event n More info about the click event lt li gt mouse double click event lt ol gt lt li gt keyboard events lt ol gt lt li gt key down event lt
80. f errors occur instead of asking the user for help This option is also used when generating formulas in HTML User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 8 RTF related options 60 21 8 RTF related options GENERATE RTF If the GENERAT tag is set to YES doxygen will generate RTF output The RTF output is optimised for Word 97 and may not look too pretty with other readers editors RTF OUTPUT RTF_OUTPUT tag is used to specify where the RTF 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 rt will be used as the default path COMPACT_RTF If the COMPACT_RTF tag is set to Y ES doxygen generates more compact RTF docu ments This may be useful for small projects and may help to save some trees in general RTF HYPERLINKS If the RTF HYPI ERLINKS tag is set to YES the RTF that is generated will con tain 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_STYLESH KET FILE Load stylesheet definitions from file Syntax is similar to doxygen s config file i e a series of assigments You on
81. f range return a character pointer See also section var and typedef 22 9 hideinitializer By default the value of a define and the initializer of a variable are displayed unless they are longer than 30 lines By putting this command in a comment block of a define or variable the initializer is always hidden See also section showinitializer User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 71 22 10 ingroup lt groupname gt lt groupname gt lt groupname gt 72 22 10 ingroup lt groupname gt lt groupname gt lt groupname gt If the ingroup command is placed in a comment block of a class file or namespace then it will be added to the group or groups identified by lt groupname gt See also page Grouping sections defgroup addtogroup and weakgroup 22 11 interface Indicates that a comment block contains documentation for an interface with name lt name gt The argu ments are equal to the class command See also section class 22 12 internal This command writes the message For internal use only to the output All text after a internal command is ignored 22 13 mainpage title If the mainpage command is placed in a comment block the block is used to customize the index page in HTML or the first chapter in BIEX The title argument is optional and replaces the default title that doxygen normally generates Here is an
82. f 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 list of the files that are included by a file in the documentation of that file JAVADOC AUTOBRIEF Ifthe JAVADOC_AUTOBRIEF is set to YES then doxygen will interpret the first line until the first dot of a JavaDoc style comment as the brief description If set to NO the default the Javadoc style will behave just like the Qt style comments 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 Ifthe 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 If member grouping is used in the documentation and the DISTRIBUTE_ GROUP_DOC tag is set to YES then doxygen will reuse the documentation of the first member in the gr
83. file boot strap zip which also contains the tar utility tar exe gzip utilities and the cygwinl 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 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 may be interested in the professional license of Ot for Windows see http www trolltech com products qt htm1 If you donate me a professional license port doxywizard for you e 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 download itat ftp ctan tug org tex archive systems win32 web2c fptex 0 3 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
84. fines JavaDoc 1 1 Qt Doc and KDOC compatible e Automatically generates class diagrams in HTML as clickable image maps and as Encap sulated PostScript images Uses the dot tool of the Graphviz tool kit to generate include dependency graphs collaboration diagrams and graphical class hierarchy graphs 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 a list of all members of a class including any inherited members along with their protection level Outputs documentation in on line format HTML and UNIX man page and off line format IATEX and RTF simultaneously any of these can be disabled if desired All formats are optimized for ease of reading Furthermore compressed HTML can be generated from HTML output using Microsofts HTML Help Workshop Windows only and PDF can be generated from the output Includes a full C preprocessor to allow proper parsing of conditional code fragments and to allow expansion of all or part of macros definitions Automatically detects public protected and private sections as well as the Qt specific signal and slots sections Extraction of private class members is optional Automatically generates references to documented classes files namespaces and members Doc umentation of global functions globals variables typedefs defines and enumerations is also sup
85. ges and mail addresses Doxygen will automatically replace any URLs and mail addresses found in the documentation by links in HTML 20 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 20 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 20 4 Links to functions Links to functions are created if one of the following patterns is encountered 1 lt functionName gt lt argument list gt 2 lt functionName gt 3 lt functionName gt 4 lt className gt lt functionName gt lt argument list gt 5 lt className gt lt functionName gt 6 lt className gt lt functionName gt where n gt 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 20 5 Links to variables typedefs enum types enum values and defines Note 3 In
86. i van Heesch 1997 2001 21 4 Input related options WARNINGS The WARNINGS tag can be used to turn on off the warning messages that are generated to standard error by doxygen Possible values are YES and NO where YES implies that the warnings are on If left blank NO is used Tip Turn warnings on while writing the documentation WARN_IF_UNDOCUMENTED If WARN_IF_UNDOCUMENTED is set to YES then doxygen will generate warnings for undocumented members If EXTRACT ALL is set to YES then this flag will automati cally be disabled WARN FORMAT The WARN_FORMAT tag determines the format of the warning messages that doxygen can produce The string should contain the file line and text tags which will be replaced by the file and line number from which the warning originated and the warning text WARN LOGFILE The WARN LOGFILE tag can be used to specify a file to which warning and error messages should be written If left blank the output is written to stderr 21 4 Input related options INPUT The INPUT tag is used to specify the files and or directories that contain documented source files You may enter file names like myfile cpp or directories like usr src myproject Separate the files or directories with spaces Note This tag and only this tag is required FILE PATTERNS Ifthe value of the INPUT tag contains directories you can use the FILE PATTERNS tag to specify mo
87. iable by putting it into group IntVariables because the second instance of IntegerVariable is undocumented ingroup A extern int VarInA Ndefgroup IntVariables Global integer variables y Q an integer variable extern int IntegerVariable 8 Ndefgroup Variables Global variables xy Q a variable in group A int VarInA int IntegerVariable 8 The priorities of grouping definitions are from highest to lowest ingroup defgroup addtogroup weakgroup The last command is exactly like addtogroup with a lower priority It was added to allow User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 5 1 Modules lazy grouping definitions you can use commands with a higher priority in your h files to define the hierarchy and weakgroup in c files without having to duplicate the hierarchy exactly Example defgroup groupl The First Group This is the first group x brief class Cl in group 1 Glass Cl b brief class C2 in group 1 class C2 funetion in group 1 void func end of groupl defgroup group The Second Group This is the second group defgroup group3 The Third Group This is the third group ay Q defgroup group4 The Fourth Group ingroup group3 Group 4 is a subgroup of group 3 A ingroup group2 brief clas
88. igned to be used for projects that make use of Troll Tech s Ot toolkit I have tried to make doxygen Qt compatible That is Doxygen can read the documentation contained in the Qt source code and create a class browser that looks very similar to the one that is generated by Troll Tech Doxygen understands the C extensions used by Qt such as signals and slots Doxygen can also automatically generate links to existing documentation that was generated with Doxygen or with Qt s non public class browser generator For a Qt based project this means that whenever you refer to members or classes belonging to the Qt toolkit a link will be generated to the Qt documentation This is done independent of where this documentation is located 13 Doxygen History Version 1 2 0 Major new features e Support for RTF output e Using the dot tool of the AT amp T s GraphViz package doxygen can now generate inheritance dia grams collaboration diagrams include dependency graphs included by graphs and graphical inher itance overviews Function arguments can now be documented with separate comment blocks Initializers and macro definitions are now included in the documentation Variables and typedefs are now put in their own section Old configuration files can be upgraded using the u option without loosing any changes Using the if and endif commands doxygen can conditionally include documentation blocks Added Doc like support for m
89. ike DECLARE_INTERFACE normal macro substitutions like PURE and THIS and plain defines like _cplusplus Note also that preprocessor definitions that are normally defined automatically by the preprocessor like _ cplusplus have to be defined by hand with doxygen s parser this is done because these defines often platform compiler specific In some cases you may want to substitute a macro name or function by something else without exposing the result to further macro substitution You can do this but using the operator instead of As an example suppose we have the following piece of code define QList OListT class QListT i Then the only way to get doxygen interpret this as a class definition for class QList is to define PREDEFINED QListT QList Here is example provided by Valter Minute that helps doxygen to wade through the boilerplate code in Microsoft s ATL library PREDEFINED DECLARE_REGISTRY_RESOURCEID DECLARE_PROTECT_FINAL_CONSTRUCT BEGIN_COM_MAP END_COM_MAP BEGIN_PROP_MAP END_PROP_MAP BEGIN_MSG_MAP END_MSG_MAP DECLARE_VIEW_STATUS STDMETHOD a HRESULT a ATL NO VTABLE N BEGIN CONNECTION POINT END CONNECTION POINT MAP DECLARE AGGREGATABLE Class DECLARE REGISTRY RESOURCEID id As you can see doxygen s preprocessor is quite powerful but if
90. il 86 var 76 verbatim 92 verbinclude 86 version 82 warning 82 acknowledgements 2 ALIASES 54 ALLEXTERNALS 62 ALPHABETICAL INDEX 56 ALWAYS SEC 52 BIN_ABSPATH 64 BINARY TOC 58 bison 4 BRIEF MEMBER DESC 52 browser 12 CASE SENSE NAMES 52 INDEX CGI_NAME 63 CGI_URL 64 CLASS DIAGRAMS 52 CLASS GRAPH 62 COLLABORATION GRAPH 63 COLS_IN ALPHA_INDEX 56 COMPACT LATEX 59 60 DISABLE_INDEX 58 DISTRIBUTE_GROUP_DOC 53 Doc 2 DOC_ABSPATH 64 DOC_URL 64 DOT PATH 63 ENABLE PREPROCESSING 61 ENABLED SECTIONS 53 ENUM_VALUES LINE 58 EXAMPLE PATH 55 EXAMPLE_PATTERNS 56 EXCLUDE 55 EXCLUDE PATTERNS 55 EXPAND AS DEFINED 61 EXPAND ONLY PREDEF 61 EXT DOC PATHS 64 EXTRA PACKAGES 59 EXTRACT ALL 51 EXTRACT PRIVATE 51 EXTRACT STATIC 51 features 35 FILE PATTERNS 55 FILTER SOURCE FILES 56 flex 4 FULL_PATH_NAMES 52 GENERATE 54 GENERATE CHI 58 GENERATE HTML 56 GENERATE HTMLHELP 58 GENERATE LATEX 58 GENERATE LEGEND 63 GENERATE MAN 60 GENERATE 60 GENERATE TAGFILE 62 GENERATE TESTLIST 54 GENERATE TODOLIST 54 GENERATE TREEVIEW 58 GPL 1 GRAPHICAL HIERARCHY 63 HAVE DOT 62 HIDE SCOPE NAMES 53 HIDE UNDOC CLASSES 51 99 HIDE UNDOC MEMBERS 51 HTML ALIGN MEMBERS 57 HTML FOOTER 57 HTML HEADER 57 HTML OUTPUT 57 HTML STYLESHEET 57 IGNORE PREFIX 56 IMAGE PATH 56
91. ile so it matches your project In the configuration file you can specify the input files and a lot of optional information You let doxygen generate the documentation based on the settings in the configuration file doxygen lt config_file gt If you have a configuration file generated with an older version of doxygen you can upgrade it to the current version by running doxygen with the u option doxygen u lt config_file gt All configuration settings in the orginal configuration file will be copied to the new configuration file Any new options will have their default value Note that comments that you may have added in the original configuration file will be lost If you want to fine tune the way the output looks doxygen allows you generate default style sheet header and footer files that you can edit afterwards User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 Note For HTML output you can generate the default header file see HTML HEADER the default footer see HTML_FOOTER and the default style sheet see HTML STYLESHEET using the following command doxygen w html header html footer html stylesheet css For LaTeX output you can generate the first part of refman tex see LATEX HEADER and the style sheet included by that header normally doxygen st y using doxygen w latex header tex doxygen st For RTF output you can generate the default style sheet file see RTF_STYLESHEET_FI
92. imitri van Heesch 1997 2001 1 4 Compiling from source on Windows when configuring with static I got Undefined first referenced symbol in file dlclose usr lib libc a nss deffinder o dlsym usr lib libc a nss deffinder o dlopen usr lib libc a nss deffinder o Manually adding Bdynamic after the target rule in Makefile doxygenand Makefile doxytag will fix this TARGET OBJECTS OBJMOC S LINK LFLAGS o TARGET OBJECTS OBJMOC LIBS Bdynamic GNU 2 7 2 x compiler problems Older versions of the GNU compiler have problems with constant strings containing characters with char acter 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 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 Since Windows comes without all the nice tools that Unix users are used to you need to install a number of these tools before you can compile doxygen for Windows Here is what is required e An unzip untar tool like WinZip to unpack the tar source distribution This can be found at http www winzip c
93. 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 down load the fancyhdr package separately You can find it at ftp ftp tex ac uk tex archive macros latex contrib supported fancyhdr e 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 tools htmlhelp wkshp downloadmain htm e 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 e the Graph visualization toolkit version 1 5 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 dos box Make sure all tools i e nmake latex gswin32 dvips sed flex bison cl rm and perl are accessible from the c
94. ink command See also section link 22 54 link lt link object gt The links that are automatically generated by doxygen always have the name of the object they point to as link text The link command can be used to create a link to an object a file class or member with a user specified link text The link command should end with an endlink command All text between the link and endlink commands serves as text for a link to the lt link object gt specified as the first argument of link See section autolink for more information on automatically generated links and valid link objects 22 55 ref lt name gt text Creates a reference to a named section subsection page or anchor For HTML documentation the reference command will generate a link to the section For a sections or subsections the title of the section will be used as the text of the link For anchor the optional text between quotes will be used or lt name gt if no text is specified For ATEX documentation the reference command will generate a section number for sections or the text followed by a page number if lt name gt refers to an anchor See also Section page for an example of the ref command 22 56 section lt section name gt section title Creates a section with name lt section name gt The title of the section should be specified as the second argument of the section command Warning This command only works inside related
95. into a single paragraph Each post condition will start on a new line Alternatively one post command may mention several postconditions The post command ends when a blank line or some other sectioning command is encountered 22 40 pre description of the precondition Starts a paragraph where the precondition of an entity can be described The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent pre commands will be joined into a single paragraph Each precondition will start on a new line Alternatively one pre command may mention several preconditions The pre command ends when a blank line or some other sectioning command is encountered 22 41 remarks remark text Starts a paragraph where one or more remarks may be entered The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent remark commands will be joined into a single paragraph Each remark will start on a new line Alternatively one remark command may mention several remarks The remark command ends when a blank line or some other sectioning command is encountered 22 42 return description of the return value Starts a return value description for a function The text of the paragraph has no special internal structure All vi
96. is approach if there is no alternative The doxytag tool may even become obsolete in the future 10 Frequently Asked Questions 1 How to get information on the index page in HTML You should use the mainpage command inside a comment block like this mainpage My Personal Index Page Nsection intro Introduction This is eto Nsubsection stepl Step 1 the introduction section install Installation Opening the box 2 Help some all of the members of my class file namespace are not documented Check the fo llowing a Is your class file namespace documented If not it will not be extracted from the sources EXTRACT ALL is set to Y unless 1 b Are the members private If so you must set EXTRACT PRIVAT appear in the documentation ES in the config file E to Y ES to make them c Is there a function macro in your class that does not end with a semicolon e g MY MACRO If so then you have to instruct doxygen s preprocessor to remove it This typically boils down to the following settings in the config file ENABLE_PREPROCESSING YES MACRO_EXPANSION YES EXPAND_ONLY_PREDEF YES PREDEFINED MACRO User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 31 32 Please read the preprocessing section of the manual for more information 3 When I set EXTRACT_ALL to
97. itten by Dimitri van Heesch 1997 2001 22 84 word AlignLeft left alignment AlignCenter center alignment AlignRight right alignment No other types of alignment are supported Note For nested lists HTML commands should be used Equivalent to arg 22 84 lt word gt Displays the parameter lt word gt using typewriter font You can use this command to refer to member function parameters in the running text Example the p x and p y coordinates are used to This will result in the following text the x and y coordinates are used to Equivalent to c 22 85 verbatim Starts a block of text that will be verbatim included both the HTML and the documentation The block should end with a endverbatim block All commands are disabled in a verbatim block Warning Make sure you include a endverbatim command for each verbatim command or the parser will get confused 22 86 This command writes a backslash character X to the HTML and output The backslash has to be escaped in some cases because doxygen uses it to detect commands 22 87 XQ This command writes an at sign to the HTML and output The at sign has to be escaped in some cases because doxygen uses it to detect JavaDoc commands User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 92 22 88 amp 22 88 amp This command writes the amp character to the
98. l enhancement commands may be used inside the paragraph Multiple adjacent exception commands will be joined into a single paragraph Each parameter description will start on a new line The exception description ends when a blank line or some other sectioning command is encountered See section fn for an example Note the tag exceptions is a synonym for this tag 22 34 lt section label gt Starts conditional documentation section The section ends with a matching endif command A conditional section is disabled by default To enable it you must put the section label after the ENABLED SECTIONS tag in the configuration file Conditional blocks can be nested A nested sec tion is only enabled if all enclosing sections are enabled as well Example Uncoditionally shown documentation Nif Condl Only included if Condl is set Nendif Nif Cond2 Only included if Cond2 is set if Cond3 Only included if Cond2 and Cond3 are set endif More text endif Unconditional text X User Manual for Doxygen 1 2 8 1 written by Dimitri Heesch 1997 2001 22 35 invariant description of invariant See also section Vendif 22 35 invariant description of invariant Starts a paragraph where the invariant of an entity can be described The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside
99. les will be gener ated 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 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 52 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 2 General options 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 HIDE_SCOPE_NAMES Ifthe 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 I
100. ll you should use setenv QTDIR SPWD instead of the export command above Now install doxygen as described above Latex problems The 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 amp Digital Unix problems If you are compiling for HP UX with aCC and you get this error opt aCC lbin ld Unsatisfied symbols alloca code then you should according to Anke Selig edit ce parse cpp and replace User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 13 Known compilation problems for Unix extern C void alloca unsigned int with include lt alloca h gt If that does not help try removing ce_parse cpp and let bison rebuilt 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__ amp amp defined sparc defined include lt alloca h gt with else not GNU C if defined __STDC__ amp amp defined sparc defined include lt alloca h gt __sparc__ __sparc__ defined defined 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 19
101. ly 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 doxy gen normally uses RTF EXT ENSIONS FILI E Setoptional 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 21 9 Man page related options GENERATE_MAN Ifthe G for classes and files ENERAT E_MAN tag is set to YES the default doxygen will generate man pages path is entered the value of OUTPUT DIRI MAN_OUTPUT The MAN_OUTPUT tag is used to specify where the man pages will be put If a relative ECTORY will be put in front of it If left blank man will be used as the default path A directory man3 will be created inside the directory specified by MAN_OUTPUT User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 10 Preprocessor related options ENSION MAN_EXT man pages default is the subroutine s section 3 MAN_LINKS Ifthe MAN_LINKS tag is set to Y ENSION tag determines the extension that is added to the generated ES and doxygen generates man output then it will generate one additional man file for each entity documented in the real man page s These additional files only
102. mands The dontinclude command sets the pointer to the first line of the example Example A test class class Test public a member function void example 1 page example dontinclude example test cpp Our main function starts like this skip main until First we create a object c t of the Test class skipline Test Then we call the example member function line example After that our little test routine ends line a Where the example file example test cpp looks as follows void main Test t t example User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 84 22 59 include lt file name gt 85 See also sections line skip skipline and until 22 59 include lt file name gt This command can be used to include a source file as a block of code The command takes the name of an include file as an argument Source files or directories can be specified using the EXAMPLE PATH tag of doxygen s configuration file If lt file name gt itself is not unique for the set of example files specified by the EXAMPLE PATH tag you can include part of the absolute path to disambiguate it Using the include command is equivalent to inserting the file into the documentation block and surround ing it with code and endcode commands The main purpose of the include command is to avoid code duplication in case of example
103. members documented in a set of HTML files A user can install these HTML files anywhere on his her hard disk or web site Therefore installdox requires the location of the documentation for each tag file lt tagfile gt that is used by doxygen The location lt location gt can be an absolute path or a URL Note Each lt tagfile gt must be unique and should only be the name of the file not including the path q When this option is specified installdox will generate no output other than fatal errors Optionally a list of HTML files may be given These files are scanned and modified if needed If this list is omitted all files in the current directory that end with html are used The installdox script is unique for each generated class browser in the sense that it knows what tag files are used It will generate an error if the option is missing for a tag file or if an invalid tag file is given 19 Output Formats The following output formats are directly supported by doxygen HTML Generated if GENERATE_HTML is set to YES in the configuration file BIFX Generated if GENERATE_LATEX is set to YES in the configuration file Man pages Generated if is set to YES in the configuration file RTF Generated if GENERATE RTF is set to YES in the configuration file Note that the RTF output probably only looks nice with Microsoft s Word 97
104. my links with real links for all generated HTML files Example Suppose you have a project proj that uses two external projects called ext 1 and ext 2 The directory structure looks as follows root proj html HTML output directory for proj SEC Sources for proj proj cpp ext1 html HTML output directory for ext1 extl tag tag file for extl ext2 html HTML output directory for ext2 ext2 tag tag file for ext2 proj cfg doxygen configuration file for proj extl cfg doxygen configuration file for ext1 ext2 cfg doxygen configuration file for ext2 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 30 Then the relevant parts of the configuration files look as follows proj cfg OUTPUT_DIRECTORY proj INPUT proj src TAGFILES extl extl tag ext2 ext2 tag extl cfg OUTPUT DIRECTORY ext1 GENERATE TAGFILE extl extl tag ext2 cfg OUTPUT_DIRECTORY ext2 GENERATE_TAGFILE ext2 ext2 tag extl html ext2 html In some hopefully exceptional cases you may have the documentation generated by doxygen but not the sources nor a tag file In this case you can use the doxytag tool to extract a tag file from the generated HTML sources This tool depends on the particular structure of the generated output and on some special markers that are generated by doxygen Since this type of extraction is brittle and error prone I suggest you to only use th
105. n The second line should be the absolute URL to the CGI script This information is taken from the configuration file e 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 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 re generate the HTML output you can simply edit the generated search cfg file and run the generated installdox script to correct the links in the documentati
106. needed By looking at the adapter class itself and its base classes you can easily see which methods need to be updated To update a language simply make your translator class derive from the abstract class Translator and pro vide translations for the methods that were previously provided by the adapter class and its base classes User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 Index 93 93 amp 93 92 lt 93 gt 93 a 87 addindex 82 addtogroup 67 76 anchor 82 Varg 87 attention 76 author 76 Vb 87 brief 77 bug 77 c 87 class 68 code 88 date 77 def 68 defgroup 69 deprecated 78 dontinclude 84 Ve 88 endcode 89 endhtmlonly 89 endif 78 endlatexonly 89 endlink 83 endverbatim 89 enum 69 example 69 exception 78 f 89 fL 90 f 90 file 70 fn 71 hideinitializer 71 htmlinclude 86 htmlonly 90 if 78 image 90 include 85 ingroup 72 interface 72 internal 72 invariant 79 latexonly 91 Vii 91 line 85 link 83 mainpage 72 namespace 73 note 79 overload 73 92 page 74 par 79 param 80 post 80 pre 80 ref 83 relates 74 remarks 80 return 80 retval 81 sa 81 section 83 showinitializer 75 since 81 skip 85 skipline 86 struct 75 subsection 84 test 81 throw 81 todo 82 typedef 75 union 76 unt
107. nt blocks XE Iu def This block can be used to put a Qt style detailed documentation block after a member The one line brief description looks as follows 1 lt There are also JavaDoc versions for detailed documentation wma E where the first sentence is the brief description if JAVADOC_AUTOBRIEF is set to YES and there is a separate brief description as well 7 lt Note that these blocks have the same structure and meaning as the special comment blocks above only the lt 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 block cannot be put after the enum FH enum EnumType int EVall lt enum value 1 int EVal2 lt enum value 2 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 19 void member lt a member function protected int value lt an integer value Warning These blocks can only be used to document members and parameters They cannot be used to doc ument files classes unions structs groups namespaces and enums themselves Furthermore the structural commands mentioned in the previous section like class are ignored inside these com ment blocks 4 Lists Doxygen has a number of ways to create lists of items Using dashes By putting a number o
108. om The good tested and free alternative is the t ar utility supplied with cygwin tools Anyway the cygwin s flex bison and sed are also recommended below e 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 e Perl 5 0 or higher for Windows This be downloaded from http www ActiveState com Products ActivePerl e 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 cygwintools zip of the cygwin tools that I put together just to compile doxygen 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 Also make sure the tools are available from a dos box by adding the directory they are in to the search path User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 1 4 Compiling from source on Windows 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
109. ommand 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 doxytag exe and doxysearch 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 15 Installating the binaries on Windows 10 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 ntm1 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 Installating the binaries on Windows There is no fancy installation procedure at the moment if anyone wants to add it 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
110. on 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 SQTDIR 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 space on your disk 3 Edit the shell script search cgi with a text editor Fill in the absolute path to the doxysearch binary after the DOXYSEARCH tag On my system this becomes DOXYSEARCH usr local bin doxysearch Fill in the absolute path to the qt documentation after the DOXYPATH tag On my system this becomes DOXYPATH usr local qt html 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 User Manual for Doxygen 1 2 8 1 written by Dimitri v
111. 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 the links that are generated by doxygen will contain dummy links You have to run the installdox script to change these dummy links into real links See Installdox usage for more information The use of dummy links may seem redundant but it is really useful if you want to move the external documentation to another location Then the documentation does not need to be regenerated by doxygen only installdox has to be run Note Because the HTML files are expected to have a certain structure only HTML files generated with doxygen or with Qt s class browser generator can be used Doxytag only reads the HTML files they are not altered in any way User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 39 Doxytag expects a list of all HTML files that form the documentation or a directory that contains all HTML files If neither is present doxytag will read all files with a html extension from the current directory
112. ort HOWTO explains how to add support for a new language to Doxygen Just follow these steps 1 Tell me for which language you want to add support If no one else is already working on support for that language you will be assigned as the maintainer for the language 2 Create a copy of translator_en h and name it translator_ lt your_2_letter_counter_code gt h I ll use xx in the rest of this document 3 Edit language cpp Add a include lt translator_xx h gt in setTranslator add else if L EQUAL your language name User Manual for Doxygen 1 2 8 1 written by Dimitri Heesch 1997 2001 theTranslator new TranslatorYourLanguage aftertheif 4 Edit libdoxygen pro in and add translator xx h to the HEADERS line in the file doxygen pro 5 Edit translator_xx h e Rename TRANSLATOR EN H to TRANSLATOR XX H twice e Rename TranslatorEnglish to TranslatorYourLanguage e In the member idLanguage change english into the name of the your language use lower case characters only Depending on the language you may also wish to change the member functions latexLanguageSupportCommand and idLanguageCharset e Edit all the strings that are returned by the member functions that start with tr Try to match punctuation and capitals To enter special characters with accents you can Enter them directly if your keyboard supports that and you are using a Latin 1 font Doxy gen will transla
113. ou 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 lt label gt PENG akuy NQ to add members to a group that is defined in more detail elsewhere Note that compound entities like classes files and namespaces can be put into multiple groups but mem bers like variable functions typedefs and enums can only be a member of one group this restriction is to avoid ambiguous linking targets Doxygen will put members into that group where the grouping definition had the highest priority f i ingroup overrides any automatic grouping definition via Conflicting grouping definitions with the same priority trigger a warning unless one definition was for a member without any explicit documentation The following example puts VarInA into group A and silently resolves the conflict for IntegerVar
114. ou did not have it already This section is divided into the following subsections Compiling from source on Unix Installating the binaries on Unix Known compilation problems for Unix Compiling from source on Windows Installating the binaries on Windows Tools used to develop doxygen 11 Compiling from source on Unix If you downloaded the source distribution you need at least the following to build the executable e The GNU tools flex bison and make e In order to generate a Makefile for your platform you need per1 see http www perl com To take full advantage of doxygen s features the following additional tools should be installed Troll Tech s GUI toolkit version 2 x y Ot see http www trolltech com products qt html This is needed to build the GUI front end e IEX distribution for instance teTeX 1 0 This is needed for generating LaTeX Postscript and PDF output e the Graph visualization toolkit version 1 5 Needed for the include dependency graphs the graphical inheritance graphs and the collaboration graphs e The ghostscript interpreter Compilation is now done by performing the following steps 1 Unpack the archive unless you already have done that gunzip doxygen S VERSION src tar gz uncompress the archive tar xf doxygen SVERSION src tar unpack it 2 Run the configure script User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 11 Compiling from source on Unix sh
115. oup if any for the other members of the group By default all members of a group must be documented explicitly 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 lt section label gt endif blocks User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 3 Options related to warning and progress messages 54 GENERATE_TODOLIST The GENERATE_TODOLIST tag can be used to enable YES or disable NO the todo list This list is created by putting todo commands in the documentation GENERATE_TESTLIST GENERATE TESTLIST tag can be used to enable YES or disable NO the test list This list is created by putting test commands in the documentation 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 This tag can be used to specify a number of aliases that acts as commands in the documenta tion An alias has the form name value For example adding sideeffect par Side Effects n will allow you to put the command sideeffect or sideeffect in the documentation which will result in a u
116. ow can I use tag files in combination with compressed HTML If you want to refer from one compressed HTML file a chm to another compressed HTML file called b chm the link in a chm must have the following format a href b chm file html gt Unfortunately this only works if both compressed HTML files are in the same directory As a result you must rename the generated index chm files for all projects into something unique and put all chm files in one directory Suppose you have a project a referring to a project b using tag file b t ag then you could rename the index chm for project a into a chm and the index chm for project b into b chm In the configuration file for project a you write User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 TAGFILES b tag b chm or you can use installdox to set the links as follows installdox lb tag b chm 7 I don t like the quick index that is put above each HTML page what do I do You can disable the index by setting DISABLE INDEX to YES Then you can put in your own header file by writing your own header and feed that to HTML HEADER 8 The overall HTML output looks different while I only wanted to use my own html header file You probably forgot to include the stylesheet doxygen css that doxygen generates You can include this by putting LINK HREF doxygen css REL stylesheet TYPE text css gt in the HEAD section of the HTML page 9 Why does
117. p sl const String amp s2 relates String A string debug function void stringDebug 22 20 showinitializer By default the value of a define and the initializer of a variable are only displayed if they are less than 30 lines long By putting this command in a comment block of a define or variable the initializer is shown unconditionally See also section hideinitializer 22 21 struct lt name gt lt header file gt lt header name gt Indicates that a comment block contains documentation for a struct with name lt name gt The arguments are equal to the class command See also section class 22 22 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 75 22 23 union lt name gt lt header file gt lt header name gt 76 22 23 union lt name gt lt header file gt lt header name gt Indicates that a comment block contains documentation for a union with name lt name gt The arguments are equal to the class command See also section class 22 24 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 equivalen
118. page documentation and not in other documentation blocks See also Section page for an example of the section command User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 57 subsection lt subsection name gt subsection title 22 57 subsection lt subsection name gt subsection title Creates a subsection with name lt subsection name gt The title of the subsection should be specified as the second argument of the subsection command Warning This command only works inside related page documentation and not in other documentation blocks See also Section page for an example of the cmdsubsection command Commands for displaying examples 22 58 dontinclude lt file name gt This command can be used to parse a source file without actually verbatim including it in the documen tation as the include command does This is useful if you want to divide the source file into smaller pieces and add documentation between the pieces Source files or directories can be specified using the EXAMPLE PATH tag of doxygen s configuration file The class and member declarations and definitions inside the code fragment are remembered during the parsing of the comment block that contained the dontinclude command For line by line descriptions of source files one or more lines of the example can be displayed using the line skip skipline and until commands An internal pointer is used for these com
119. pecies of small furry animals gathered together in a cave and grooving with a pict version 4 0 date 1996 1998 It crashes a lot and requires huge amounts of memory The class introduces the more bugs the longer it is used warning This class may explode in your face warning If you inherit anything from this class you re doomed sel class WindowsNT 22 28 brief brief description Starts a paragraph that serves as a brief description For classes and files the brief description will be used in lists and at the start of the documentation page For class and file members the brief description will be placed at the declaration of the member and prepended to the detailed description A brief description may span several lines although it is advised to keep it brief A brief description ends when a blank line or another sectioning command is encountered If multiple brief commands are present they will be joined See section author for an example Synonymous to short 22 29 bug bug description Starts a paragraph where one or more bugs may be reported The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent bug commands will be joined into a single paragraph Each bug description will start on a new line Alternatively one bug command may mention several bugs The bug
120. r Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 e Since it impossible to test all possible code fragments it is very well possible that some valid piece of C C code is not handled properly If you find such a piece please send it to me so I can improve doxygen s parsing capabilities Try to make the piece of code you send as small as possible to help me narrow down the search e Using declarations for member are not yet supported They are simply ignored Using declarations for class and using directives are supported however e Doxygen does not work properly if there are multiple classes structs or unions with the same name in your code It should not crash however rather it should ignore all of the classes with the same name except one e Some commands do not work inside the arguments of other commands Inside a HTML link i e lt a href gt lt a gt for instance other commands including other HTML commands do not work The sectioning commands are an important exception e Redundant braces can confuse doxygen in some cases For example void f int is properly parsed as a function declaration but const int a is also seen as a function declaration with name int because only the syntax is analysed not the semantics If the redundant braces can be detected as in int a 20 then doxygen will remove the braces and correctly parse the result e Not all names in code fragments that are
121. re wildcard patterns like cpp and h to filter out the source files in the directories If left blank all files are included i e wildcard 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_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 directo ries 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 5 Alphabetical index options 56 EXAMPLE 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 and to filter out the source files in the directories If left blank all files are included
122. rite 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 N n 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 3 3 Documenting compound members 18 define MAX a b gt 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 Note 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 3 3 Documenting compound 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 doxygen has the following additional comme
123. s C3 in group 2 class C3 ingroup group2 brief class C4 in group 2 ud class C4 ingroup group3 brief class C5 in link group3 the third group endlink 1 5 ingroup groupl group2 group3 group4 namespace N1 is in four groups link groupl The first group endlink group2 group3 group4 Also see ref mypage2 namespace N1 Qfile ingroup group3 brief this file in group 3 Xy defgroup group5 The Fifth Group User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 5 2 Member Groups This is the fifth group page mypagel This is a section in group 5 Text of the first section page mypage2 This is another section in group 5 Text of the second section xf addtogroup groupl More documentation for the first group another function in group 1 void func2 yet another function in group 1 void func3 5 2 Member Groups If a compound e g a class or file has many members it is often desired to group them together Doxygen already automatically groups things together on type and protection level but maybe you feel that this is not enough or that that default grouping is wrong For instance because you feel that members of different syntactic types belong to the same semantic group A member group is defined by a
124. s on are linked in externally This saves a lot of memory Availability For some projects that are documented with doxygen the sources may just not be available If any of the above apply you can use doxygen s tag file mechanism A tag file is basically a compact representation of the entities found in the external sources Doxygen can both generate and read tag files To generate a tag file for your project simply put the name of the tag file after the GENERATE TAGFILE option in the configuration file To combine the output of one or more external projects with your own project you should specify the name of the tag files after the TAGFILES option in the configuration file A tag file does not contain information about where the external documentation is located This could be a directory or an URL So when you include a tag file you have to specify where the external documentation is located There are two ways to do this At configuration time just assign the location of the output to the tag files specified after the TAGFILES configuration option If you use a relative path it should be relative with respect to the directory where the HTML output of your project is generated After compile time if you do not assign a location to a tag file doxygen will generate dummy links for all external HTML references It will also generate a perl script called installdox in the HTML output directory This script should be run to replace the dum
125. ser defined paragraph with heading Side Effects You can put n s in the value part of an alias to insert newlines MAX_INITIALIZER LINES The MAX INITIALIZER LINES tag determines the maximum number of lines that the initial value of a variable or define can be If the initializer consists of more lines than specified here it will be hidden Use a value of 0 to hide initializers completely The appearance of the value of individual variables and defines can be controlled using showinitializer or hideinitializer command in the documentation OPTIMIZE OUTPUT FOR C Setthe OPTIMIZE OUTPUT FOR C tag to YES if your project consists of C sources only Doxygen will then generate output that is more tailored for C For instance some of the names that are used will be different The list of all members will be omitted etc SHOW USED FILES Set the SHOW USED F ILES 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 21 3 Options related to warning and progress messages QUIET The QUIET tag can be used to turn on off the messages that are generated to standard output by doxygen Possible values are YES and NO where YES implies that the messages are off If left blank NO is used User Manual for Doxygen 1 2 8 1 written by Dimitr
126. source the real man page but without them the man command would be unable to find the correct page The default is NO 21 10 Preprocessor related options ENABL E_PREP ROCE SSING If the ENABL ESSING tag is set to YES the default doxygen will evaluate all C preprocessor directives found in the sources and include files MACRO EXPANSION Ifthe MACRO expansion can be done a controlled way by setting 1 EXPAND_ONLY_PR ED INCLUD EARCH_INCLUDI EF IN ED tags INCLUDE_PATH The INCLUDI ES Ifthe 51 EF If the EXPAND ONLY PRED YES then the macro expansion is limited to the macros specified with the PRED PAND AS D EXPANSION tag is set to Y EARCH INCLUDES tag is set to YI ES doxygen will expand all macro names in the source code If set to NO the default only conditional compilation will be performed Macro EXPAND ON Y PRED EFto YES E PATH see below will be searched if a include is found EF and MACRO EXPANSION tags are both set to EFINED and EX ES the default the includes files in the E PATH tag can be used to specify one or more directories that contain include files that are not input files but should be processed by the preprocessor PRED EFINED The PRED EFIN
127. spectively the title of the page the current date and time only the current date the version number of doxygen the project name see PROJECT_NAME or the project number see PROJECT_NUMBER See also section Doxygen usage for information on how to generate the default header that doxygen normally uses HTML FOOTER HTML FOOTER tag 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 lt BODY gt and a lt HTML gt tag A minimal example lt BODY gt lt HTML gt If the tag is left blank doxygen will generate a standard footer The following commands have a special meaning inside the header Stitle datetime Sdate Sdoxygenversion Sprojectname projectnumber Doxygen will replace them by respectively the title of the page the current date and time only the current date the version number of doxygen the project name see PROJECT_NAME or the project number see PROJECT_NUMBER See also section Doxygen usage for information on how to generate the default footer that doxygen normally uses I HTML STYLESHEET HTML STYLESHEET tag be used to specify a user defined cascading style sheet that is used by each HTML page It can be used to fine tune the look of the HTML output If the tag is left blank doxygen will generate a default style sheet See
128. sual enhancement commands may be used inside the paragraph Multiple adjacent return commands User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 80 22 43 retval return value gt description will be joined into a single paragraph The return description ends when a blank line or some other sectioning command is encountered See section fn for an example 22 43 retval return value gt 1 description Starts a return value description for a function with name lt return value gt Followed by a description of the return value The text of the paragraph that forms the description has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent retval commands will be joined into a single paragraph Each return value description will start on a new line The retval description ends when a blank line or some other sectioning command is encountered 22 44 sa references Starts a paragraph where one or more cross references to classes functions methods variables files or URL may be specified Two names joined by either or are understood as referring to a class and one of its members One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method name Synonymous to see See also section autolink for information on how to create links to objects 22 45 Nsince tex
129. t This tag can be used to specify since when version or time an entity is available The paragraph that follows since does not have any special internal structure All visual enhancement commands may be used inside the paragraph The since description ends when a blank line or some other sectioning command is encountered 22 46 test paragraph describing a test case Starts a paragraph where a test case can be described The description will also add the test case to a separate test list The two instances of the description will be cross referenced Each test case in the test list will be preceded by a header that indicates the origin of the test case 22 47 throw lt exception object gt exception description Synonymous to exception see section exception Note the tag throws is a synonym for this tag User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 81 22 48 todo paragraph describing what is to done 22 48 todo paragraph describing what is to be done Starts a paragraph where a TODO item is described The description will also add an item to a separate TODO list The two instances of the description will be cross referenced Each item in the TODO list will be preceded by a header that indicates the origin of the item 22 49 version version number Starts a paragraph where one or more version strings may be entered The paragraph will be indented The text of the p
130. t to typedef and fn See also section fn and typedef 22 25 weakgroup lt name gt 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 22 26 attention attention text Starts a paragraph where a message that needs attention may be entered The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent attention commands will be joined into a single paragraph The attention command ends when a blank line or some other sectioning command is encountered 22 27 author list of authors Starts a paragraph where one or more author names may be entered The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent author commands will be joined into a single paragraph and separated by commas Alternatively one author command may mention several authors The author command ends when a blank line or some other sectioning command is encountered User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 28 brief brief description Example class WindowsNT brief Windows Nice Try author Bill Gates author Several s
131. t to YES EXTRACT_PRIVATE Ifthe EXTRACT_PRIVATE tag is set to YES all private members of a class will be included in the documentation EXTRACT_STATIC Ifthe EXTRACT_STATIC tag is set to YES all static members of a file will be in cluded in the documentation HIDE_UNDOC_MEMBERS If the HIDE UNDOC MEMBERS tag is set to YES doxygen will hide all undoc umented members inside documented classes or files If set to NO the default these members will be included in the various overviews but no documentation section is generated This option has no effect if EXTRACT_ALL is enabled HIDE_UNDOC_CLASSES If the HIDE UNDOC CLASSESS tag is set to YES doxygen will hide all un documented classes If set to NO the default these classes will be included in the various overviews This option has no effect if EXTRACT_ALL is enabled User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 2 General options BRIEF MEMBER DESC If the BRIEF_MEMBER_DESC tag is set to YES the default doxygen will in clude 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 REPEAT BRIEF tag is set to YES the default doxygen will prepend the brief description of a member or function before
132. taking one of a fixed set of values like OUTPUT LANGUAGE a combo is used For items taking an integer value from a range a spinbox is used For free form string type options there is a one line edit field For options taking a lists of strings a one line edit field is available with a button to add this string to the list and a button to remove the selected string from the list There is also a 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 Installdox usage Installdox is a perl script that is generated by doxygen whenever tag files are used See TAGFILES in section External reference options or the search engine is enabled See SEARCHENGINE in section Search engine options The script is located in the same directory where the HTML files are located Its purpose is to set the location of the external documentation for each tag file and to set the correct links to the search engine at install time Calling installdox with option h at the command line will give you a brief description of the usage of the program The following options are available User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 l lt tagfile gt lt location gt Each tag file contains information about the files classes and
133. tation block This is not according the JavaDoc specification however where the first sentence of the docu mentation 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 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 14 3 1 Special documentation blocks 15 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 TVall lt enum value TVall TVal2 lt enum value TVal2 TVal3 lt enum value TVal3 enumPtr enum pointer Details enumVar lt enum variable Details constructor A more elaborate description of the constructor Test A destructor A more elaborate description of the destructor Test normal member taking two arguments and returning integer value param a an integer argument param s a constant character pointer see Test see
134. tation to a different directory or URL you can simply run the script again and all links in the HTML files will be updated Example 2 To generate a tag file of the Qt documentation you can do the following doxytag t qt tag SQTDIR html A typical example to use doxytag to generate a search index is doxytag s search idx User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 40 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 be low Doxysearch must be run as a CGI binary This implies the following e There must be a HTTP daemon running on the system where you want to install the documentation the target e 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 In order to be able to search fast and efficient doxysearch does not search the generated documentation directly Instead it uses an index file that should be generated with doxytag The index file is extracted from the generated HTML files and contains all words and substrings of words present in the HTML files in a compact form together with their frequencies and links Although I tried to store all inform
135. te the characters to proper Latex and leave the Html and man output for what it is which is fine if idLanguageCharset is rone Use html codes like amp auml for an a with an umlaut i e See the HTML specification for the codes 6 Runconfigure and make again from the root of the distribution in order to regenerated the Makefiles 7 Now you can use OUTPUT LANGUAGE your language name in the config file to generate output in your language 8 Send translator xx h to me so can add it to doxygen Maintaining a language As new versions of doxygen appear new sentences will be added to the Translator interface class Of course these need to be translated as well otherwise doxygen wouldn t even compile Waiting until all language maintainers have translated these new sentences and sent the results would not be very practical for me Instead new class TranslatorAdapter x y z will be added to translator adapter h here x y and z corre spond to the current version of doxygen And all translators that previous derived from Translator will now derive from this adapter class The Adapter class contains the new sentences with default translations using the English translator which is always up to date Instead of deriving your TranslatorXX class directly from Translator it will derive from the intermediate class TranslatorAdapter x y z Thus if a translator class inherits from a adapter class maintenance is
136. this is often comfortable it may sometimes be better to put the documentation somewhere else For some types of documentation blocks like file documentation this is even required 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 as long as you put a structural command inside the documentation block Structural commands like all other commands start with a backslash or an at sign in 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 1 55 is used to indicate that the comment block contains documentation for the class Test Other structural commands are struct to document a C struct union to document a union enum to document an enumeration type to document a function var to document a variable or typedef or enum value def to document a define file to documenta file namespace to document a namespace See section Special Commands for detailed information about these and other commands Note that the documentation block belonging to a file should always contain a structural command To do
137. 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 e Section Troubleshooting tells you what to do when you have problems The second part forms a reference manual User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 CONTENTS 2 e 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 Section Doxygen usage shows how to use the doxygen program Section Doxytag usage shows how to use the doxyt ag 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 th
138. tscript 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 ormake pdf_2onl 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
139. uired for instance Netscape 4 0 or Internet explorer 4 0 TRE EVIEW WIDTH If the treeview is enabled see GENERATE TREEVIEW then this tag can be used to 21 7 set the initial width in pixels of the frame in which the tree is shown LaTeX related options ERATE LATEX If the GENERATE LATEX tag is set to YES the default doxygen will generate output User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 58 21 7 LaTeX related options LATEX_OUTPUT The LATEX_OUTPUT tag is used to specify where the IATEX 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 latex will be used as the default path COMPACT LATEX If the COMPACT_LATEX tag is set to YES doxygen generates more compact documents This may be useful for small projects and may help to save some trees in general PAPER_TYPE The PAPER_TYPE tag can be used to set the paper type that is used by the printer Possible values are a4 210 x 297 mm a4wide same as a4 but including the a4wide package letter 8 5 x 11 inches legal 8 5 x 14 inches executive 7 25 x 10 5 inches If left blank a4wide will be used EXTRA_PACKAGES The EXTRA PACKAGES tag can be used to specify one or more IZTEX package names that should be included in th
140. untered Example class Test Normal text par User defined paragraph Contents of the paragraph par New paragraph under the same heading note This note consists of two paragraphs This is the first paragraph par And this is the second paragraph 0X Xo More normal text User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 22 38 lt parameter name gt 4 parameter description class Test 22 38 parameter name parameter description Starts a parameter description for a function parameter with name lt parameter name gt Followed by a description of the parameter The existence of the parameter is not checked The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent param commands will be joined into a single paragraph Each parameter description will start on a new line The param description ends when a blank line or some other sectioning command is encountered See section fn for an example 22 39 post description of the postcondition Starts a paragraph where the postcondition of an entity can be described The paragraph will be indented The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent post commands will be joined
141. ur 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 DOC_ABSPATH The DOC_ABSPATH tag should be the absolute path to the directory where the documen tation 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 in stalled 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 Examples Suppose you have a simple project consisting of two files a source file example cc and a header file example h Then a minimal configuration file is as simple as INPUT example cc example h Assuming the example makes use of Qt classes and perl is located in usr bin a more realistic config uration file would be PROJECT NAME Example INPUT example cc example h WARNINGS YES TAGFILES qt tag PERL_PATH usr bin perl SEARCHENGINE NO To generate the documentation for the Odbt Tabular package I have used the following configuration file PROJECT NAME QdbtTabular OUTPUT DIRECTORY html WARNINGS YES INPUT examples examples
142. uration 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 212 EXAMPLE PATTERNS 21 4 ALLEXTERNALS 21 11 EXCLUDE 21 4 ALPHABETICAL INDEX 21 5 EXCLUDE PATTERNS 21 4 ALWAYS DETAILED SEC 21 2 EXPAND AS DEFINED 21 10 _ 21 13 EXPAND ONLY PREDEF 21 10 BINARY TOC 21 6 EXT DOC PATHS 21 13 BRIEF MEMBER DESC 21 2 EXTRA PACKAGES 21 7 CASE_SENSE_NAMES 21 2 EXTRACT_ALL 21 2 21 13 EXTRACT_PRIVATE 21 2 CGLURL 21 13 EXTRACT STATIC 212 CLASS DIAGRAMS 21 2 FILE PATTERNS 21 4 CLASS GRAPH 21 12 FILTER SOURCE FILES 21 4 COLLABORATION GRAPH 21 12 FULL PATH NAMES 21 2 COLS_IN ALPHA_INDEX 21 5 GENERATE BUGLIST 21 2 COMPACT LATEX 21 7 GENERATE CHI 21 6 COMPACT 21 8 GENERATE HTML 21 6 DISABLE_INDEX 21 6 GENERATE HTMLHELP 21 6 DISTRIBUTE_GROUP_DOC 21 2 GENERATE LATEX 21 7 DOC ABSPATH 21 13 GENERATE LEGEND 21 12 DOC_URL 21 13 GENERATE_MAN 21 9 DOT_PATH 21 12 21 8 ENABLE_PREPROCESSING 21 10 GENERATE_TAGFILE 21 11 ENUM VALUES PER LINE 21 6 GENERATE TESTLIST 212 ENABLED SECTIONS 21 2 GENERATE TODOLIST 21 2 EXAMPLE PATH 21 4 GENERATE TREEVIEW 21 6 User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 21 2 General options GRAPHICAL HIERARCHY 21 12 OUTPUT_LANGUAGE 21 2 HAVE_DOT 21 12 PAPER_TYPE 21 7 HIDE_SCOPE_NAMES 21 2 PDF_HYPERLINKS 21 7
143. use ghost view to view it User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 1 2 Installating the binaries on Unix 1 2 Installating the binaries on Unix If you downloaded the binary distribution for Unix you can install doxygen by typing configure make install Binaries are installed in the directory lt prefix gt bin documentation and examples in the direc tory lt prefix gt share doc packages doxygen use make install DOCDIR lt path gt to change this lt prefix gt defaults to usr but can be changed with the prefix 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 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 13 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 SPWD If you have a csh like she
144. xygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 62 21 13 Search engine options COLLABORATION_GRAPH If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen will generate a graph for each documented class showing the direct and indirect implemen tation dependencies inheritance containment and class references variables of the class with other documented classes INCLUDE GRAPH If the ENABLE PREPROCESSING SEARCH INCLUDES INCLUDE_GRAPH and HAVE DOT tags are set to YES then doxygen will generate a graph for each documented file showing the direct and indirect include dependencies of the file with other documented files INCLUDED BY GRAPH If the ENABLE PREPROCESSING SEARCH INCLUDES INCLUDED BY GRAPH and HAVE DOT tags are set to YES then doxygen will generate a graph for each documented header file showing the documented files that directly or indirectly include this file 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 DOT PATH This tag can be used to specify the path where the dot tool can be found If left blank it is assumed the dot tool can be found on the path MAX DOT GRAPH HEIGHT The MAX DOT GRAPH HEIGHT tag can be used to set the maximum allows height in pixels of the graphs generated by dot If
145. y links to their documen tation if possible Special example documentation block added This can be used to provide cross references between the documentation and some example code Documentation blocks can now be placed inside the body of a class Documentation blocks with line range may now be created using special C line comments Unrelated members can now be documented A page containing a list of these members is generated Added an include command to insert blocks of source code into the documentation Warnings are generated for members that are undocumented You can now specify your own HTML headers and footers for the generated pages Option added to generated indices containing all external classes instead of only the used ones Version 0 1 Initial version 14 Doxygen usage Doxygen is a command line based utility Calling doxygen with the help option at the command line will give you a brief description of the usage of the program All options consist of a leading character followed by one character and one or more arguments depend ing on the option To generate a manual for your project you typically need to follow these steps You document your source code with special documentation blocks see section Special documentation blocks You generate a configuration file see section Configuration by calling doxygen with the g option doxygen g lt config_file gt You edit the configuration f
146. you want even more flexibility you can always write an input filter and specify it after the INPUT_FILTER tag If you are unsure what the effect of doxygen s preprocessing will be you can run doxygen as follows doxygen d Preprocessor This will instruct doxygen to dump the input sources to standard output after preprocessing has been done Hint set QUIET YES andWARNINGS NO in the configuration file to disable any other output User Manual for Doxygen 1 2 8 1 written by Dimitri van Heesch 1997 2001 9 Linking to external documentation If your project depends on external libraries or tools there are several reasons to not include all sources for these with every run of doxygen Disk space Some documentation may be available outside of the output directory of doxygen already for instance somewhere on the web You may want to link to these pages instead of generating the documentation in your local output directory Compilation speed External projects typically have a different update frequency from your own project It does not make much sense to let doxygen parse the sources for these external project over and over again even if nothing has changed Memory For very large source trees letting doxygen parse all sources may simply take too much of your system s memory By dividing the sources into several packages the sources of one package can be parsed by doxygen while all other packages that this package depend

Manual for version 1.2.8.1 Written by Dimitri van Heesch c 1997-2001

Contents

Download Pdf Manuals

Related Search

Related Contents