Home

Manual for version 1.5.6 Written by Dimitri van Heesch c 1997-2007

1. Doxywizard Your application custo output rea en XML files doxmlparser lib Config file Doxyfile spi J make ps postscript c pp Geca Latex files latex read generate update m gt Makefile make pdf PDF read Sources Doxygen m ur H read rea generate N Man pages Custom headers H footers Tag file s rU i images Windows only H i i import doc MS Word generate i i HTML read m x Doxytag o pages HTML Help Workshop parse i L i 1 1 Figure 1 Doxygen information flow 7 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 be an entire source tree that is recursively scanned To simplify the creation of a configuration file doxygen can create a template configuration file for you To do this call doxygen from the command line with the g option doxygen g config file where lt config file gt is the name of the configuration file If you omit the file name a file named Doxyfile will be created If a file with the name lt c
2. This is the first group brief class Cl in group 1 class Cl brief class C2 in group 1 class C2 function in group 1 void func end of groupl defgroup group2 1 The Second Group This is the second group Gdefgroup group3 1 This is the third rhe Third Group group defgroup group4 1 ingroup group3 rhe Fourth Group Group 4 is a subgroup of group 3 ingroup group2 brief class C3 in group 2 class C3 ingroup group2 brief class C4 in group 2 class C4 ingroup group3 brief class C5 in link group3 the third group endlink class C5 ingroup groupl group2 group3 group4 namespace is in four groups sa link groupl The first group endlink group2 group3 group4 Also see ref mypage2 namespace 1 file ingroup group3 brief this file in group 3 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 29 defgroup group5 The Fifth Group 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 end of group5 addtogro
3. Nenum Test TEnum A description of the enum type Nvar Test TEnum Test Vall The description of the first enum value User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 87 56 example lt file name gt Indicates that a comment block contains documentation for a source code example The name of the source file is file name The text of this file will be included in the documentation just after the documentation contained in the comment block All examples are placed in a list The source code is 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 Nexample 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 looks as follows void main
4. because doxygen only allows one brief and one detailed description Furthermore if there is one brief description before a declaration and one before a definition of a code item only the one before the declaration will be used If the same situation occurs for a detailed description the one before the definition is preferred and the one before the declaration will be ignored Here is an example of a documented piece of C code using the Qt style A test class more elaborate class description class Test public An enum More detailed enum description enum TEnum 11 x Enum value TVall x TVal2 x Enum value TVal2 x TVal3 lt Enum value TVal3 Enum pointer Details x xenumPtr Enum variable Details enumVar A constructor more elaborate description of the constructor Test A destructor more elaborate description of the destructor x Test A normal member taking two arguments and returning an integer value param a integer argument param s a constant character pointer return The test results sa Test Test testMeToo and publicVar int testMe int a const char xs A pure virtual member sa testMe param cl the first argument param c2 the second argument virtual void testMeToo char cl char c2 0 public variable
5. virtual QCString trFiles return Files This is the localized implementation of newer equivalent using the obsolete method trFiles virtual QCString trFile bool first_capital bool singular if first_capital amp amp singular return trFiles possibly localized obsolete method else return english trFile first capital singular User Manual for Doxygen 1 5 6 written by Dimitri van Heesch c 1997 2006 134 The trFiles is not present in the TranslatorEnglish class because it was removed as obsolete However it was used until now and its call was replaced by trFile true false in the doxygen source files Probably many language translators implemented the obsolete method so it perfectly makes sense to use the same language dependent result in those cases The TranslatorEnglish does not implement the old method It derives from the abstract Translator class On the other hand the old translator for a different language does not implement the new t rFile method Because of that it is derived from another base class TranslatorAdapter x yz The TranslatorAdapter x 2 class have to implement the new required t rFile method However the translator adapter would not be compiled if the tz Files method was not implemented This is the reason for implementing the old method in the translator adapter class using the same code that was removed from the TranslatorEnglish
6. PERLMOD LATEX tags to YES in your Doxyfile 3 Run Doxygen on your Doxyfile doxygen Doxyfile 4 A perlmod subdirectory should have appeared in your output directory Enter the perlmod subdi rectory and run make pdf This should generate a doxylatex pdf with the documentation in PDF format 5 Run make dvi This should generate a doxylatex dvi with the documentation in DVI format User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 130 181 Perl Module documentation format The Perl Module documentation generated by Doxygen is stored in DoxyDocs pm This is a very simple Perl module that contains only two statements an assigment to the variable doxydocs and the customary 1 statement which usually ends Perl modules The documentation is stored in the variable doxydocs which can then be accessed by a Perl script using DoxyDocs pm doxydocs contains a tree like structure composed of three types of nodes strings hashes and lists e Strings These are normal Perl strings They can be of any length can contain any character Their semantics depends on their location within the tree This type of node has no children Hashes These are references to anonymous Perl hashes A hash can have multiple fields each with a different key The value of a hash field can be a string a hash or a list and its semantics depends on the key of the hash field and the location of the hash within the tree T
7. Test t t example See also section include 57 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 i e the line after file is left blank then the documentation block that contains the file command will belong to the file it is located in 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 x file file h User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 88 A brief file description A more elaborated file description global integer value More details about this value extern int globalValue Note In the above example JAVADOC_AUTOBRIEF has been set to YES in the configuration file 58 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 only needed if a comment block is not placed in front or behind 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 omitted A full function declaration including arguments should be
8. COM COM MAP x PROP PROP N MSG ND MSG PROPERTY MAP ND PROPERTY OBJECT D OBJECT ECLARE VIEW STATUS N STDMETHOD a HRESULT a ATL NO VTABLE BEGIN CONNECTION POINT MAP x END CONNECTION POINT 2 2 gt DECLARE_DYNAMIC class IMPLEMENT DYNAMIC classl 1 2 DECLARE 1 IMPLEMENT DYNCREATE classl 1 2 IMPLEMENT_SERIAL classl class2 1 3 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 DECLARE_MESSAGE_MAP TRY try CATCH_ALL e catch END_CATCH_ALL THROW_LAST throw RUNTIME_CLASS class class MAKEINTRESOURCE nId nId IMPLEMENT REGISTER v y z ASSERT x assert x ASSERT_VALID assert x TRACEO x printf x OS ERR A B A B __cplusplus DECLARE OLECREATE class BEGIN_DISPATCH_MAP classl class2 BEGIN_INTERFACE_MAP 1 51 class2 INTERFACE PART class id END INTERFACE MAP DISP FUNCTION class name function result END DISPATCH MAP IMPLEMENT OLECREA
9. 0 virtual ULONG Release 0 1 Note that PREDEFINED tag accepts function like macro definitions like 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 are 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 QListT class QListT Then the only way to get doxygen interpret this as class definition for class QList is to define PREDEFINED QListT QList Here is an example provided by Valter Minute and Reyes Ponce that helps doxygen to wade through the boilerplate code in Microsoft s ATL amp libraries PREDEFINED DECLARE INTERFACE 1 name V STDMETHOD result name virtual result name PURE 0 THIS_ THIS ECLARE_REGISTRY_RESOURCEID DECLARE_PROTECT_FINAL_CONSTRUCT ECLARE_AGGREGATABLE Class DECLARE_REGISTRY_RESOURCEID Id ECLARE_MESSAGE_MAP 55 ND MESSAGE MAP
10. EXAMPL E PATH tag contains directories you can use the ERNS tag to specify one or more wildcard pattern like and h to filter out the source files in the directories If left blank all files are included IMAGE PATH The IMAGI images that are to be INPUT FILTER The E PATH tag be used to specify or more files or directories that contain included in the documentation see the image command 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 lt input file gt where filter is the value of the IN PUT 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 PATTERNS basis Doxygen will compare the file name with each pattern and apply the filter if there is a match The filters are a list of the form pattern filter like cpp my_cpp_filter See INPUT FILTI The FILTER PATTI is applied to all files FILTER SOURCE FII INPUT FILTER will also be used to filter the input files that are used for producing the source files to browse i e when SOURCE BROWSER is set to YES ES Ifthe FILTI 5 ERNS tag can be used to specify filters a per file pattern ER
11. Starts a return value description for a function The text of the paragraph has no special internal structure All visual enhancement commands may be used inside the paragraph Multiple adjacent return commands 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 105 retval return value gt 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 106 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 107 see references Equivalent t
12. User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 18 x Details int publicVar A function variable x Details int handler int a int b The one line comments contain a brief description whereas the multi line comment blocks contain a more detailed description The brief descriptions are included in the member overview of a class namespace or file and are printed using a small italic font this description can be hidden by setting BRIEF MEMBER DESC to NO in the config file By default the brief descriptions become the first sentence of the detailed descriptions but this can be changed by setting the REPEAT BRIEF tag to NO Both the brief and the detailed descriptions are optional for the Qt style By default a JavaDoc style documentation block behaves the same way as a Qt style documentation block This is not according the JavaDoc specification however where the first sentence of the documentation block is automatically treated as a brief description To enable this behaviour you should set JAVADOC AUTOBRIEF to YES in the configuration file If you enable this option and want to put a dot in the middle of a sentence without ending it you should put a backslash and a space after it Here is an example Brief description e g using only a few words Details follow Here is the same piece of code as shown above this time documented using the JavaDoc style and
13. 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 HIDE_SCOPE_NAMES If the HIDE_SCOPE_NAMES tag is set to NO the default then doxygen will show members with their full class and namespace scopes in the documentation If set to YES the scope will be hidden SHOW_INCLUDE_FILES If the SHOW INCLUDE FILES tag is set to YES the default then doxygen will put a list of the files that are included by a file in the documentation of that file 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 DCCS 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 SORT BRIEF DOCS If the SORT BRIEF DOCS tag is set to YES then doxygen will sort the brief de scriptions of file namespace and class members alphabetically by member name If set to NO the default the members will appear in declaration order SORT_GROUP_NAMES Ifthe SORT GROUP NAMES tag is set to YES then doxygen will sort the hierarchy of group names into
14. Test t t example See also sections line skip skipline and until 126 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 107 The main purpose of the include command is to avoid code duplication in case of example 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 Mine skip skipline and until commands Note Doxygen s special commands do not work inside blocks of code It is allowed to nest C style com ments inside a code block though See also section example dontinclude and section verbatim 127 includelineno lt file name gt This command works the same way as include but will add line numbers to the included file See also section include 128 Mine pattern This com
15. WS X11 INCLUDE MENUITEM DEF EXPAND ONLY PREDEF YES EXPAND 5 DEFINED Q OBJECT FAKE Q OBJECT ACTIVATE SIGNAL WITH PARAM O VARIANT AS 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 Special Commands 46 Introduction All commands the documentation start with a backslash V or an at sign 9 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 sharp braces are used the argument is a single word e If round braces are used the argument extends until the end of the line 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch c 1997 2006 82 a addindex addtogroup anchor arg attention author b brief bug e callgraph callergraph category class code cond copybrief copydetails copydoc date def defgroup deprecated details dir dontinclude dot dotfile e els
16. 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 read both statements i e static CONST_STRING version 2 xx static CONST_STRING version 1 xx 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 35 you have to set the EXPAND ONLY PREDEF tag to YES and specify the macro definitions after the PREDEFINED or EXPAND AS DEFINED tag A typically example where some help from the preprocessor is needed is when dealing with Microsoft s _declspec language extension is an example function extern C void __declspec dllexport ErrorMsg String aMessage When nothing is done doxygen will be confused and see declspec as some sort of function To help doxygen one typically uses the following preprocessor settings ENABLE PREPROCESSING YES MACRO EXPANSION YES EXPAND ONLY PREDEF
17. 115 115 116 116 116 117 117 117 117 117 118 118 118 118 118 118 118 119 124 128 128 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 181Perl Module documentation format 130 182Data structure describing the Perl Module documentation tree 130 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS Introduction Doxygen is a documentation system for C C Java Objective C Python IDL Corba and Microsoft flavors Fortran VHDL PHP C and to some extent D It can help you in three ways 1 3 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 You can configure doxygen to extract the code structure from undocumented source files This is very useful to quickly find your way in large source distributions You can also visualize the relations between the various elements by means of include dependency graphs inheritance diagrams and collaboration diagrams which are all generated automatically You can even abuse doxygen
18. In other words the up to date language translators do not need the TranslatorAdapter_x_y_z classes at all and you do not need to implement anything else than the methods required by the Translator class i e the pure virtual methods of the Translator they end with 0 If everything compiles fine try to run translator py and have a look at the translator report ASCII file at the doxygen doc directory Even if your translator is marked as up to date there still may be some remarks related to your souce code Namely the obsolete methods that are not used at all may be listed in the section for your language Simply remove their code and run the translator py again Also you will be informed when you forgot to change the base class of your translator class to some newer adapter class or directly to the Translator class If you do not have time to finish all the updates you should still start with the most radical approach as described above You can always change the base class to the translator adapter class that implements all of the not yet implemented methods If you prefer to update your translator gradually have a look at TranslatorEnglish the translator file Inside you will find the comments like new since 1 2 4 that separate always a number of methods that were implemented in the stated version Do implement the group of methods that are placed below the comment that uses the same version numbers as your transla
19. 1997 2006 108 skipline pattern is equivalent to skip pattern line pattern See section dontinclude for an example 131 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 132 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 133 htmlinclude lt file name gt This command includes the file lt file name gt as is in the HTML documentation The command is equiv 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 134 a lt word gt Displays
20. Manual for version 1 5 6 Written by Dimitri van Heesch 1997 2007 CONTENTS Contents I 10 11 12 13 14 15 16 17 18 19 20 21 User Manual Compiling from source on Unix Installing the binaries on Unix Known compilation problems for Unix Compiling from source on Windows Installing the binaries on Windows Tools used to develop doxygen Step 1 Creating a configuration file Step 2 Running doxygen Step 3 Documenting the sources Special documentation blocks Putting documentation after members Documentation at other places Special documentation blocks in Python Special documentation blocks in VHDL Modules Member Groups Subpaging Links to web pages and mail addresses Links to classes Links to files Links to functions 10 11 12 14 15 19 20 23 24 26 29 30 37 37 38 38 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 22 Links to variables typedefs enum types enum values and defines 23 typedefs 24 Output Formats 25 Simple aliases 26 Aliases with arguments 27 Nesting custom command II Reference Manual 28 Format 29 Project related options 30 Build related options 31 Options related to warning and progress messages 32 Input related options 33 Source browsing related options 34 Alphabetical index options 35 HTML related options 36
21. The input of doxytag consists of a set of HTML files Important If you use tag files 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 56 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 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 htm1 extension from the current directory 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 publ
22. The simplest way would be to pass the arguments to the English translator and to return its result Instead the adapter uses the old trFiles in one special case when the new trFile true false is called This is the mostly used case at the time of introducing the new method see above While this may look too complicated the technique allows the developers of the core sources to change the Translator interface while the users may not even notice the change Of course when the new t rFile is used with different arguments the English result is returned and it will be noticed by non English users Here the maintainer of the language translator should implement at least that one particular method What says the base class of a language translator If the language translator class inherits from any adapter class the maintenance is needed In such case the language translator is not considered up to date On the other hand if the language translator derives directly from the abstract class Translator the language translator is up to date The translator adapter classes are chained so that the older translator adapter class uses the one step newer translator adapter as the base class The newer adapter does less adapting work than the older one The oldest adapter class derives indirectly from all of the adapter classes The name of the adapter class is chosen so that its suffix is derived from the previous official version of doxygen that d
23. User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 113 147 endcode Ends a block of code See also section code 148 enddot Ends a blocks that was started with dot 149 endmsc Ends a blocks that was started with msc 150 endhtmlonly Ends a block of text that was started with a htmlonly command See also section htmlonly 151 endlatexonly Ends a block of text that was started with a latexonly command See also section latexonly 152 endmanonly Ends a block of text that was started with a manonly command See also section manonly 153 endverbatim Ends a block of text that was started with a verbatim command See also section endcode section verbatim User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 114 154 endxmlonly Ends a block of text that was started with a xmlonly command See also section xmlonly 155 f Marks the start and end of an in text formula See also section formulas for an example 156 Marks the start of a long formula that is displayed centered on a separate line See also section f and section formulas 157 Mj Marks the end of a long formula that is displayed centered on a separate line See also section f and section formulas 158 f environment Marks the start of a formula that is in a specific environment Note The second is optional and is on
24. YES PREDEFINED _ declspec This will make sure the __declspec dllexport is removed before doxygen parses the source code For a more complex example suppose you have the following obfuscated code fragment of an abstract base class called IUnknown A reference to IID x ifdef _ cplusplus define REFIID const IID amp else define REFIID const IID 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 YES EXPAND_ONLY_PREDEF YES PREDEFINED DECLARE INTERFACE 1 name STDMETHOD result name virtual result name PURE 0 THIS_ THIS Ccplusplus we can make sure that the proper result is fed to doxygen s parser A reference to an IID define REFIID The IUnknown interface class IUnknown User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 36 virtual HRESULT QueryInterface REFIID iid void ppv 0 virtual ULONG AddRef
25. AUTOBRIEF to YES in the configuration file 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 11 Putting documentation after members If you want to document the members of a file struct union class or enum and you want to put the documentation for these members inside the compound it is sometimes desired to place the documentation block after the member instead of before For this purpose you have to put an additional marker in the comment block Note that this also works for the parameters of a function Here are some examples int var x Detailed description after the member This block can be used to put a Qt style detailed documentation block after a member Other ways to do the same are int var x lt Detailed description after the member User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 or int var lt Detailed description after the member Or int var Detailed description after the member 7 lt Most often on
26. Indicates that a comment block contains documentation for a variable or enum value either global or as a member of a class This command is equivalent to typedef and fn See also section fn and typedef 80 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 81 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 82 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 Each author description will start a new line Alternatively one author command may mention several authors The author command ends when a blank line or some other sectioning command is encountered Example Nclass WindowsNT brief Windows Nic
27. PHP only 178 version 112 protectedsection PHP only 178 warning 113 protocol 72 weakgroup 80 public PHP only 178 xmlonly 168 ublicsection PHP onl 178 xrefitem Ww y ji Wef 119 173 lat 73 relates 170 relatesalso 74 169 remarks 103 amp 172 return 104 iu 171 retval 105 lt 175 section 121 174 see 107 177 The following subsections provide a list of all commands that are recognized by doxygen Unrecognized commands are treated as normal text User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 84 Structural indicators 47 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 Naddtogroup mygrp x Additional documentation for group mygrp x function void funcl Another function x void func2 See also page Grouping sections defgroup ingroup and weakgroup 48 callgraph When this command is put in a comment block of a function or method and HAVE_DOT is set to YES then doxygen will generate a call graph for that functio
28. Suppose you have a project a referring to a project b using tag file b tag 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 TAGFILES b tag b chm User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 47 10 11 12 13 or you can use installdox to set the links as follows installdox lb tag b chm 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 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 Why does 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 How can I exclude all test directories from my directory tree S
29. The at sign has to be escaped in some cases because doxygen uses it to detect JavaDoc commands User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 118 171 Languageld This command enables disables a language specific filter This can be used to put documentation for different language into one comment block and use the OUTPUT_LANGUAGE tag to filter out only a specific language Use language_id to enable output for a specific language only and to enable output for all languages this is also the default mode Example N english This is english dutch Dit is Nederlands german Dieses ist deutsch output for all languages 172 amp This command writes the amp character to output This character has to be escaped because it has a special meaning in HTML 173 28 This command writes the character to the output This character has to be escaped some cases because it is used to expand environment variables 174 This command writes the character to the output This character has to be escaped in some cases because it is used to refer to documented entities 175 lt This command writes the lt character to the output This character has to be escaped because it has a special meaning in HTML 176 gt This command writes the gt character to the output This character has to be escaped because it has a special meaning in HTML 177 This command wr
30. The title of the section should be specified as the second argument of the section command Warning This command only works inside related page documentation and not in other documentation blocks 122 Nsubsection 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 a section of a related page documentation block and not in other documentation blocks See also Section page for an example of the subsection command 123 subsubsection lt subsubsection name gt subsubsection title Creates a subsubsection with name lt subsubsection name gt The title of the subsubsection should be specified as the second argument of the subsubsection command Warning This command only works inside a subsection of a related page documentation block and not in other documentation blocks See also Section page for an example of the subsubsection command 124 paragraph lt paragraph name gt paragraph title Creates a named paragraph with name lt paragraph name gt The title of the paragraph should be specified as the second argument of the paragraph command Warning This command only works inside a subsubsection of a related page documentation block and not in other documentation blocks See also Section page for an example of the paragraph
31. parser If all source files would include a common header file for instance the class and type definitions and their documentation would be present in each translation unit The preprocessor is written using flex and can be found in src pre 1 For condition blocks if evaluation of constant expressions is needed For this a yacc based parser is used which can be found in src constexp yand src constexp l The preprocessor is invoked for each file using the preprocessFile function declared in src pre h and will append the preprocessed result to a character buffer The format of the charac ter buffer is 0x06 file name 1 0x06 preprocessed contents of file 1 0x06 file name n 0x06 preprocessed contents of file n Language parser The preprocessed input buffer is fed to the language parser which is implemented as a big state ma chine using flex It can be found in the file src scanner 1 There is one parser for all languages C C 4 Java IDL The state variables insideIDL and insideJava are uses at some places for lan guage specific choices The task of the parser is to convert the input buffer into a tree of entries basically an abstract syntax tree An entry is defined in src ent ry h andis blob of loosely structured information The most important User Manual for Doxygen 1 5 6 written by Dimitri van Heesch c 1997 2006 126 field is sect ion which specifies the kind of information contained in the entry Poss
32. 1ex is parsing some input Fortunately when flex is used with the d option it outputs what rules matched This makes it quite easy to follow what is going on for a particular input fragment To make it easier to toggle debug information for a given flex file I wrote the following perl script which automatically adds or removes d from the correct line in the Makefile usr local bin perl Sfile shift ARGV print Toggle debugging mode for S file n add or remove the d flex flag in the makefile unless rename Makefile libdoxygen Makefile libdoxygen old print STDERR Error cannot rename Makefile libdoxygen Mn exit 1 if open F Makefile libdoxygen old unless open G gt Makefile libdoxygen print STDERR Error opening file Makefile libdoxygen for writing n exit 1 print Processing Makefile libdoxygen n while lt F gt if s LEX P a zA Z YY t file LEX d 1 t file g print Enabling debug info for file n elsif s LEX d P a zA Z YY t file LEX P 1YY t file g print Disabling debug info for S file n 750 close F User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 128 unlink Makefile libdoxygen old else print STDERR Warning file Makefile libdoxygen old does not exist n touch the file Snow time utime Snow Snow file Perl Module Output format Sinc
33. 38 35 35 36 44 38 41 37 43 30 30 35 39 44 44 44 35 30 30 30 30 30 44 35 35 35 35 35 35 29 34 32 44 42 User Manual for Doxygen 1 5 6 written by Dimitri Heesch 1997 2006 61 INHERIT_DOCS INLINE_INFO INLINE_INHERITED_MEMB INLINE SOURCES INPUT INPUT ENCODING FILTER INTERNAL DOCS JAVADOC AUTOBRIEF LATEX BATCHMODE LATEX_CMD_NAME LATEX_HEADER LATEX HIDE INDICES LATEX OUTPUT MACRO EXPANSION MAKEINDEX CMD NAME MAN EXTENSION MAN LINKS MAN OUTPUT DOT GRAPH DEPTH INITIALIZER LINES MSCGEN PATH MULTILINE 15 BRIEF OPTIMIZE FOR FORTRAN OPTIMIZE_OUTPUT_FOR_C OPTIMIZE_OUTPUT_JAVA OPTIMIZE_OUTPUT_VHDL OUTPUT_DIRECTORY OUTPUT LANGUAGE PAPER TYPE PDF HYPERLINKS PERL PATH PERLMOD LATEX PERLMOD PRETTY PERLMOD MAKEVAR PREFIX PREDEFINED PROJECT NAME 29 30 29 33 32 32 32 30 29 36 36 36 36 36 42 36 38 38 38 44 30 44 29 29 29 29 29 29 29 36 36 43 41 41 41 42 29 PROJECT_NUMBER QT_AUTOBRIEF QUIET RECURSIVE REFERENCED BY RELATION REFERENCES RELATION REFERENCES LINK SOURCE REPEAT BRIEF RTF EXTENSIONS FILE RTF_HYPERLINKS RTF_OUTPUT RTF_STYLESHEET FILE SEARCH_INCLUDES SEARCHENGINE SEPARATE_MEMBER PAGES SHORT_NAMES SHOW_DIRECTORIES SHOW FILES SHOW INCLUDE
34. 5 6 written by Dimitri van Heesch c 1997 2006 133 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 translate the characters to proper IATEX and leave the HTML and man output for what it is which is fine if idLanguageCharset is set correctly Use html codes like amp auml for an a with an umlaut i e See the HTML specification for the codes 7 Run configure and make again from the root of the distribution in order to regenerated the Makefiles 8 Now you can use OUTPUT LANGUAGE your language name in the config file to generate output in your language 9 Sendtranslator xx htomesolIcan add it to doxygen Send also your name and e mail address to be included in the maintainers txt list Maintaining a language New versions of doxygen may use new translated sentences In such situation the Translator class requires implementation of new methods its interface changes Of course the English sentences need to be translated to the other languages At least new methods have to be implemented by the language related translator class otherwise doxygen wouldn t even compile Waiting until all language maintainers have translated the new sentences and sent the results would not be very prac
35. 99 post 100 pre 100 property 92 protocol 92 ref 104 relates 92 relatesalso 93 remarks 100 return 101 retval 101 sa 101 section 105 see 101 showinitializer 93 INDEX 137 since 101 DOCSET_FEEDNAME 72 skip 107 DOT CLEANUP 79 skipline 107 DOT_FONTNAME 78 struct 93 DOT_FONTPATH 78 subpage 104 subsection 105 subsubsection 105 test 101 throw 102 todo 102 tparam 100 typedef 93 union 93 until 108 var 94 verbatim 117 verbinclude 108 version 102 warning 102 xmlonly 117 xrefitem 102 118 ABBREVIATE BRIEF 63 acknowledgements 3 ALIASES 64 ALLEXTERNALS 77 ALPHABETICAL INDEX 70 ALWAYS DETAILED SEC 63 BINARY TOC 72 bison 4 BRIEF MEMBER DESC 62 browser 13 BUILTIN STL SUPPORT 64 CALL_GRAPH 78 CALLER GRAPH 79 CASE SENSE NAMES 63 CHM FILE 72 CLASS DIAGRAMS 77 CLASS GRAPH 78 COLLABORATION GRAPH 78 COLS IN ALPHA INDEX 70 73 74 CPP_CLI_SUPPORT 64 CREATE_SUBDIRS 62 DETAILS AT 64 DIRECTORY GRAPH 79 DISABLE INDEX 72 DISTRIBUTE GROUP 64 Doc 4 3 MAX NODES 79 DOT IMAGE FORMAT 79 DOT MULTI TARGET 79 DOT PATH 79 DOT TRANSPARENT 79 DOTFILE DIRS 79 DOXYFILE ENCODING 62 ENABLE PREPROCESSING 76 ENABLED SECTIONS 67 ENUM VALUES PER LINE 73 EXAMPLE PATH 69 EXAMPLE PATTERNS 69 EXAMPLE RECURS
36. Ends an inline text fragment with a specific style HTML only e lt STRONG gt Starts a section of bold text e lt STRONG gt Ends a section of bold text e SUB Starts a piece of text displayed in subscript e lt SUB gt Ends a SUB section e SUP Starts a piece of text displayed in superscript e lt SUP gt Ends a lt SUP gt section e lt TABLE gt starts a table e lt TABLE gt ends a table e lt TD gt Starts a new table data element e lt TD gt Ends a table data element e lt TR gt Starts a new table row e lt TR gt Ends a table row e lt TT gt Starts a piece of text displayed in a typewriter font e lt TT gt Ends a TT section e lt KBD gt Starts a piece of text displayed in a typewriter font e lt KBD gt Ends a lt KBD gt section e lt UL gt Starts an unnumbered item list e lt UL gt Ends an unnumbered item list e VAR Starts a piece of text displayed in an italic font e lt VAR gt Ends a VAR section The special HTML character entities that are recognized by Doxygen e amp copy the copyright symbol User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 122 e amp tm the trade mark symbol e amp reg the registered trade mark symbol e amp 1t less than symbol e amp gt greater than symbol e amp amp ampersand e amp apos single quotation mark straight e amp quot double quotation mark str
37. HTML commands should be used Equivalent to arg 165 Forces new line Equivalent to lt br gt and inspired by the printf function User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 117 166 p lt word gt Displays the parameter lt word gt using a 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 167 verbatim Starts a block of text that will be verbatim included in both the HTML and the IZTEX 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 See also section code and section verbinclude 168 xmlonly Starts a block of text that will be verbatim included in the generated XML output only The block ends with a endxmlonly command This command can be used to include custom XML tags See also section htmlonly and section latexonly 169 This command writes a backslash character X to the HTML output The backslash has to be escaped in some cases because doxygen uses it to detect commands 170 This command writes an at sign to the HTML and output
38. Heesch 1997 2006 112 public Executable a command on the server void Command int commandId i 144 dotfile lt file gt caption Inserts an image generated by dot from lt file gt into the documentation The first argument specifies the file name of the image doxygen will look for files in the paths or files that you specified after the DOTFILE_DIRS tag If the dot file is found it will be used as an input file to the dot tool The resulting image will be put into the correct output directory If the dot file name contains spaces you ll have to put quotes around it The second 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 145 lt word gt Displays the argument lt word gt in italics Use this command to emphasize words Example Typing this is a really good example will result in the following text this is a really good example Equivalent to vem To emphasis multiple words use lt em gt multiple words lt em gt 146 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
39. I have rewritten practically all code since then DOC has still given me a good start in writing doxygen All people at Troll Tech for creating a beautiful GUI Toolkit which is very useful as a Win dows Unix platform abstraction layer Kevin McBride for maintaining the subversion reporsitory for doxygen My brother Frank for rendering the logos Harm van der Heijden for adding HTML help support Wouter Slegers of Your Creative Solutions for registering the www doxygen org domain Parker Waechter for adding the RTF output generator Joerg Baumann for adding conditional documentation blocks PDF links and the configuration generator Matthias Andree for providing a spec script for building rpms from the sources Tim Mensch for adding the todo command Christian Hammond for redesigning the web site Ken Wong for providing the HTML tree view code Talin for adding support for C style comments with XML markup Petr Prikryl for coordinating the internationalisation support All language maintainers for providing translations into many languages 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 5 6 written by Dimitri van Heesch 1997 2006 Part I User Manual Installation First go to the download page http www doxygen org download html to get the latest distribution if you did not have
40. 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 Incase all classes in a project start with a common prefix all classes will be put under the same header in the alphabetical index The IGNORE tag can be used to specify a prefix or a list of prefixes that should be ignored while generating the index headers 35 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 5 6 written by Dimitri van Heesch 1997 2006 71 HTML_OUTPUT The HTML_OUTPUT tag is used to specify where the HTML docs will be put If a relative path is entered the value of OUTPUT_DIRECTORY will be put in front of it If left blank html will be used as the default path HTML FILE EXTENSION The HTML FILE EXTENSION tag can be used to specify the file extension for each generated HTML page for example htm php asp If it is left blank doxygen will generate files with html ext
41. JavaDoc style comment as the brief description If set to NO the default the Javadoc style will behave just like regular Qt style comments thus requiring an explicit brief command for a brief description QT_AUTOBRIEF If the OT AUTOBRIEF is set to YES then doxygen will interpret the first line until the first dot of a Qt style comment as the brief description If set to NO the default the Qt style will behave just like regular Qt style comments thus requiring an explicit brief command for a brief description User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 64 BUILTIN STL SUPPORT If you use STL classes i e std string std vector etc but do not want to include a tag file for the STL sources as input then you should set this tag to YES in order to let doxygen match functions declarations and definitions whose arguments contain STL classes e g func std string v s func std string This also make the inheritance and collaboration diagrams that involve STL classes more complete and accurate CPP CLI SUPPORT If you use Microsoft s C CLI language you should set this option to YES to enable parsing support SIP_SUPPORT Set the SIP SUPPORT tag to YES if your project consists of sip sources only Doxygen will parse them like normal C but will assume all classes use public instead of private inheritance when no explicit protection keyword is present PROPE
42. TAGFILES filel file2 Adding location for the tag files is done as follows TAGFILES filel locl files 1002 where loci and 1 2 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 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 ALI a tag file that is based on the input files it reads See section Doxytag usage for more information about the usage of tag files EXT PER PATH EXTERNALS Ifthe ALLEXT ERNALS tag is set to YES alle ERNAL GROUPS If the EXT ERNAL GROUPS tag is set to YI xternal class will be listed in the class index If set to NO only the inherited external classes will be listed ES all external groups will be listed in the modules index If set to NO only the current project s groups will be listed ERL PATH should be the absolute path and name of the perl script interpreter i e the result of which perl 44 Dot options CLASS_DIAGRAMS If the CLASS_DIAGRAMS tag is set
43. 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 handy for code reviews for instance 8 Step 2 Running doxygen To generate the documentation you can now enter doxygen config file Depending on your settings doxygen will create html rtf latex xml and or man directories inside the output directory As the names suggest these directories contain the generated documentation in HTML RTF BIEX XML and Unix Man page format The default output directory is the directory in which doxygen is started The root directory to which the output is written can be changed using the OUTPUT DIRECTORY The format specific directory within the output directory can be selected using the HTML OUTPUT RTF OUTPUT OUTPUT XML OUTPUT and MAN OUTPUT tags of the configuration file If the output directory does not exist doxygen will try to create it for you but it will not try to create a whole path recursively like mkdir p does User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 8 1 HTML output 13 8 1 HTML output The generated HTML documentation can be viewed by pointing a HTML browser to the index html file in the htm1 directory For the best results a browser that supports cascading st
44. a new bug first search through the database if the same bug has already been submitted by others the doxygen product will be preselected If you believe you have found a new bug please report it If you are unsure whether or not something is a bug please ask help on users mailing list first subscription is required If you send only a vague description of a bug you are usually not very helpful and it will cost me much more time to figure out what you mean In the worst case your bug report may even be completely ignored by me so always try to include the following information in your bug report e The version of doxygen you are using for instance 1 5 3 use doxygen version if you are not sure e The name and version number of your operating system for instance SuSE Linux 6 4 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 use doxygen s u configName to strip the comments from an existing config file e The easiest and often the only way for me to fix bugs is if you can attach a small example demon strating the problem you have to the bug report so I can reproduce it on my machine Please make sure the example is valid source code could potentially compile and that the problem is really cap tured by the example I often get examples that do not trigger the actual bug If you intend to send more than one file plea
45. 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 4 include in the class documentation In most cases you can use STRIP FROM INC PATH to strip a user defined part of a path You can also document your class as follows 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 quotes instead of angle brackets you should type Nclass MyClassName myhdr h path myhdr h Docs for MyClassName 6 How 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 lt 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
46. command User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 106 Commands for displaying examples 125 dontinclude lt file name gt This command can be used to parse a source file without actually verbatim including it in the documentation 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 Mine skip skipline and until commands An internal pointer is used for these commands The dontinclude command sets the pointer to the first line of the example Example A test class class Test public member function void example Npage example dontinclude example test cpp Our main function starts like this skip main until First we create a object Nc t of the Test class skipline Test Then we call the example member function Mine example After that our little test routine ends x line Where the example file example test cpp looks as follows void main
47. event 2 key up event More text here If you use tabs for indentation within lists please make sure that TAB_SIZE in the configuration file is set to the correct tab size You can end a list by starting a new paragraph or by putting a dot on an empty line at the same indent level as the list you would like to end Here is an example that speaks for itself Text before the list list item 1 sub item 1 sub sub item 1 sub sub item 2 The dot above ends the sub sub item list More text for the first sub item The dot above ends the first sub item More text for the first list item sub item 2 0X X F F HF X User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 26 sub item 3 list item 2 More text in the same paragraph More text in a new paragraph x X 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 consist 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 li gt key up event lt ol gt lt ul gt Mor
48. for creating normal documentation as I did for this manual Doxygen is developed under Linux and Mac OS X but is set up to be highly portable As a result it runs on most other Unix flavors as well Furthermore executables for Windows are available This manual is divided into three parts each of which is divided into several sections The first part forms a user manual Section Installation discusses how to download compile and install doxygen for your platform Section Getting started tells you how to generate your first piece of documentation quickly Section Documenting the code demonstrates the various ways that code can be documented Section Lists show various ways to create lists Section Grouping shows how to group things together Section Including formulas shows how to insert formulas in the documentation Section Graphs and diagrams describes the diagrams and graphs that doxygen can generate Section Preprocessing explains how doxygen deals with macro definitions Section Automatic link generation shows how to put links to files classes and members in the documentation Section Output Formats shows how to generate the various output formats supported by doxygen Section Custom Commands show how to define and use custom commands in your comments Section Linking to external documentation explains how to let doxygen create links to externally generated documentation Section Frequently Asked Questions gives answers to
49. for further info on how filters are used If FILTER PATTERNS is empty INPUT FILTER E FIL ES tag is set to YES the input filter if set using 33 Source browsing related options SOURCE BROWSI ER Ifthe SOURCE BROWS ER tag is set to YES then a list of source files will be generated Documented entities will be cross referenced with these sources Note To get rid of all source code in the generated output make sure also VERBATIM HE ADERS is set to NO INLINE SOURCES Setting the INLINE SOURCI classes STRIP CODE COMMI ES tag and enums directly into the documentation ENTS Setting the STRIP CO to YES will include the body of functions DE 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 70 REFERENCED BY RELATION Ifthe REFERENCED_BY_RELATION tag is set to YES then for each doc umented function all documented functions referencing it will be listed REFERENCES RELATION Ifthe REFERENCES_RELATION tag is set to YES then for each documented function all documented entities called used by that function will be listed REFERENCES_L
50. from the Folder Tree View Gf specified The default is YES 31 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 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 IF DOC ERROR If WARN IF DOC ERROR is set to YES doxygen will generate warnings for po tential errors in the documentation such as not documenting some parameters in a documented function or documenting parameters that don t exist or using markup commands wrongly WARN NO PARAMDOC This WARN_NO_PARAMDOC option can be abled to get warnings for functions that are documented but have no documentation for their parameters or return value If set to NO the default doxygen will only warn about wrong or incomplete parameter documentation but not about the absence of documentation WARN FO
51. http sourceforge net projects unxutils This packages contains the tools 1ex and bison which are needed during the compilation process if you use User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 a CVS snapshot of doxygen the official source releases come with pre generated sources Download the zip extract it to e g c tools unxutils Now you need to add adjust the following environment variables via Control Panel System Advanced Environment Variables e add c tools unxutils usr local wbin to the start of PATH e set BISON_SIMPLE to c tools unxutils usr share bison simple Download doxygen s source tarball and put it somewhere e g use tools Now start a new command shell and type cd c tools gunzip doxygen x y z src tar gz tar xvf doxygen x y z src tar to unpack the sources Now your environment is setup to build doxygen and doxyt ag Inside the doxygen x z directory you will find a winbuild directory containing a Doxygen sln file Open this file in Visual Studio You can now build the Release or Debug flavor of Doxygen and Doxytag by right clicking the project in the solutions explorer and selecting Build Note that compiling Doxywizard currently requires Qt version 3 see http www trolltech com products qt qt3 If you do not have a commercial license you build Doxywizard with the open source version see http qtwin sourceforge net qt3 win32 compile msvc 2005
52. in combination with member grouping to avoid that doxygen puts a member group as a subgroup of a Public Protected Private section 68 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 Any other documentation that is inside the documentation block will by appended after the generated message User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 91 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 overload 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 hi void Test drawRect int x int y int w int h void Test drawRect const Rect amp r Nclass Test Morief A short description text fn void Test drawRect int x int y int w int h This command draws a rectangle
53. into a single paragraph Each bug description will start on a new line Alternatively one bug command may mention several bugs The bug command ends when a blank line or some other sectioning command is encountered See section author for an example 85 cond lt section label gt Starts a conditional section that ends with a corresponding endcond command which is typically found in another comment block The main purpose of this pair of commands is to conditionally exclude part of a file from processing in older version of doxygen this could only be achieved using C preprocessor commands The section between cond and endcond commands can be included by adding its section label to the ENABLED SECTIONS configuration option If the section label is omitted the section will be excluded from processing unconditionally For conditional sections within a comment block one should use a Vif endif block Conditional sections can be nested In this case a nested section will only be shown if it and its containing section are included Here is an example showing the commands in action An interface x class Intf public A method virtual void func 0 cond TEST A method used for testing virtual void test 0 endcond cond DEV implementation of the interface User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 96 class
54. is the first in the list Instead of adding structure using the approach decribed in section modules it is often more natural and convienent to add additional structure to the pages using the subpage command For a page A the subpage command adds a link to another page B and at the same time makes page B a subpage of A This has the effect of making two groups GA and GB where GB is part of GA page A is put in group GA and page B is put in group GB User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 31 Including FormulasDoxygen allows you to put IZTEX formulas in the output this works only for the HTML and ATEX 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 e latex the IEX compiler needed to parse the formulas To test I have used the teTeX 1 0 distri bution e dvips a tool to convert DVI files to PostScript files I have used version 5 92b from Radical Eye software for testing e gs the GhostScript interpreter for converting PostScript files to bitmaps I have used Aladdin GhostScript 8 0 for testing There are three ways to include formulas in the documentation 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 5 1 1 and f x_2 y_2 f is f sqrt x
55. it already This section is divided into the following sections Compiling from source on Unix Installing the binaries on Unix Known compilation problems for Unix Compiling from source on Windows Installing the binaries on Windows Tools used to develop doxygen 1 Compiling from source on Unix If you downloaded the source distribution you need at least the following to build the executable The GNU tools flex bison and GNU make and strip In order to generate a Makefile for your platform you need perl see http www perl com The configure script assume the availibility of standard Unix tools such as sed date find uname mv cp cat echo tr cd and rm To take full advantage of doxygen s features the following additional tools should be installed Troll Tech s GUI toolkit Ot see http www trolltech com products qt html ver sion 3 3 or higher This is needed to build the GUI front end doxywizard A BIEX distribution for instance teTeX 1 0 par see http www tug org interest html free This is needed for generating La TeX Postscript and PDF output the Graph visualization toolkit version 1 8 10 or higher par see http www graphviz org Needed for the include dependency graphs the graph ical inheritance graphs and the collaboration graphs If you compile graphviz yourself make sure you do include freetype support which requires the freetype library and header files otherwise the graphs will not r
56. 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 60 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 61 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 62 interface lt name gt lt header file gt lt header name gt 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 63 internal This command writes the message For internal use only to the output and all text after an internal command until the end of the comment block or the end of the section whichever comes first is marked as internal If the internal command is put inside a section see for example section all subsection after the command are considered to be internal as well Only a n
57. of Ent ry objects in the entry tree The field Ent ry tagInfo is used to mark the entry as external and holds information about the tag file Documentation parser Special comment blocks are stored as strings in the entities that they document There is a string for the brief description and a string for the detailed description The documentation parser reads these strings and executes the commands it finds in it this is the second pass in parsing the documentation It writes the result directly to the output generators The parser is written in C and can be found in src docparser cpp The tokens that are eaten by the parser come from src doctokenizer Code fragments found in the comment blocks are passed on to the source parser The main entry point for the documentation parser is validatingParseDoc declared in src docparser h For simple texts with special commands validatingParseText is used Source parser If source browsing is enabled or if code fragments are encountered in the documentation the source parser is invoked The code parser tries to cross reference to source code it parses with documented entities It also does syntax highlighting of the sources The output is directly written to the output generators The main entry point for the code parser is parseCode declared in src code h User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 127 Output generators After data is
58. 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 dummy links with real links for all generated HTML files Example Suppose you have a project pro j 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 sre 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 ofg doxygen configuration file for proj extl cfg doxygen configuration file for extl ext2 cfg doxygen configuration file for ext2 Then the relevant parts of the configuration files look as follows proj cfg OUTPUT DIRECTORY proj INPUT proj src TAGFILES extl extl tag extl html ext2 ext2 tag ext2 html extl cfg OUTPUT_DIRECTORY extl GENERATE TAGFILE extl extl tag ext2 cfg OUTPUT_DIRECTORY ext2 GENERATE_TAGFILE ext2 ext2 tag User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 45 In some hopefully exceptional cases you
59. out out std logic Mux output end entity brief Architure definition of the MUX details More details about this mux element architecture behavior of mux using with is begin with sel select out lt din 0 when 0 din 1 when others end architecture To get proper looking output you need to set OPTIMIZE OUTPUT VHDL to Y ES in the config file This will also affect a number of other settings When they were not already set correctly doxygen will produce a warning telling which settings where overruled ListsDoxygen provides a number of ways to create lists of items User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 25 Using dashes By putting a number of column aligned minus signs at the start of a line a bullet list will automatically be generated Numbered lists can also be generated by using a minus followed by a hash Nesting of lists is allowed and is based on indentation of the items Here is an example A list of events mouse events mouse move event 4 mouse click event n More info about the click event mouse double click event keyboard events key down event key up event More text here F X 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
60. pro duce a search index and a PHP script to search through the index For this to work the doc User Manual for Doxygen 1 5 6 written by Dimitri van Heesch c 1997 2006 80 umentation should be viewed via a web server running PHP version 4 1 0 or higher See http www php net manual en installation php for installation instructions 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 doc src FILE PATTERNS cc h INCLUDE_PATH examples TAGFILES qt tag PERL_PATH usr local bin perl SEARCHENGINE YES To regenerate the Qt 1 44 documentation from the sources you could use the following config file PROJECT_NAME Qt OUTPUT_DIRECTORY gt docs HIDE UNDOC MEMBERS YES HIDE UNDOC CLASSES ES ENABLE PREPROCESSING ES IO IO IO IO IO IO IO IO IO IO IO IO IO IO GC Xv H K
61. specified after the fn command on a single line since the argument ends at the end of the line Warning Do not use this command if it is not absolutely needed since it will lead to duplication of information and thus to errors Example class Test public const char xmember char int throw std out of range const char xTest member char c int n throw std out of range Nclass Test brief Test class Details about Test fn 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 of range return a character pointer f X X See also section var and typedef 59 headerfile lt header file gt lt header name gt Intended to be used for class struct or union documentation where the documentation is in front of the definition The arguments of this command are the same as the second and third argument of cmdclass User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 89 The header file name refers to the file that should by included by the application to obtain the definition of the class struct or union 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
62. to base super classes and inherited overridden members are generated automatically Includes a fast rank based search engine to search for strings or words in the class and member documentation You can type normal HTML tags in your documentation Doxygen will convert them to their equiv alent BIEX 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 52 Although doxygen can now be used in any project written in a language that is supported by doxygen i
63. tolerant in recovering from typos in formulas It may be necessary to remove the file formula repository that is written to the html directory to get rid of an incorrect formula Graphs and diagramsDoxygen has built in support to generate inheritance diagrams for C classes Doxygen can use the dot tool from graphviz 1 5 to generate more advanced diagrams and graphs Graphviz is an open sourced cross platform graph drawing toolkit and can be found at http www graphviz org If you have the dot tool available in the path you can set HAVE DOT to YES in the configuration file to let doxygen use it Doxygen uses the dot tool to generate the following graphs if GRAPHICAL HIERARCHY is set to YES a graphical representation of the class hierarchy will be drawn along with the textual one Currently this feature is supported for HTML only Warning When you have a very large class hierarchy where many classes derive from a common base class the resulting image may become too big to handle for some browsers 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 built 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 COLLABORAT
64. with a left upper corner at x Na width Na w and height a h overload void Test drawRect const Rect amp r 69 package lt name gt Indicates that a comment block contains documentation for a Java package with name name 70 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 IEX generator starts a new section in the chapter Page documentation Example Npage pagel A documentation page Leading text Nsection sec An example section This page contains the subsections ref subsectionl and ref subsection2 For more info see page ref page2 subsection subsectionl The first subsection Text subsection subsection2 The second subsection More text x page page2 Another page User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 92 Even more info 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 MYPAGE1 or mixed case letters e g MyPagel in the lt name gt argument you should set CASE SENSE 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 al
65. 2 x 1 2 y 2 y 1 2 results in The distance between 21 01 and x2 is zxo 1 yo y1 2 Unnumbered displayed formulas that are centered on a separate line These formulas should be put between M and M commands An example I 2 2Mleft int_ 0 T left u a t Nint Ngamma t frac d theta k theta t int_ a theta c xi u_t xi t d xi right dt right NE results in T a 40 0 iss i w t fuan RS doule 3 Formulas or other latex elements that are not in a math environment can be specified using f environment where environment is the name of the environment the corresponding end command is f Here is an example for an equation array f eqnarray g amp amp N rac Gm 2 r 2 NN amp amp frac 6 673 Ntimes 10 11 mbox m 3 mbox kg 1 mbox s 2 5 9736 times 10 24 mbox kg 6371 01 mbox km 2 NN amp amp 9 82066032 Nmbox m s 2 which results in Gm r2 6 673 x 1071 m s 5 9736 x 1024 kg 6371 01 km 9 82066032 m s User Manual for Doxygen 1 5 6 written by Dimitri Heesch 1997 2006 32 For the first two commands one should make sure formulas contain valid commands in IZTEX s math mode For the third command the section should contain valid command for the specific environment Warning Currently doxygen is not very fault
66. 6 74 If left blank a4wide will be used EXTRA PACKAGES The 5 tag can be used to specify one or more package names that should be included in IZTEX 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 IATEX header for the gener ated IATEX 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 title datetime date doxygenversion 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 IATEX that is generated is prepared for conversion to PDF using ps2pdf or pdflatex 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 vie
67. CS 64 INLINE INFO 66 INLINE INHERITED MEMB 63 INLINE SOURCES 69 INPUT 68 INPUT ENCODING 68 INPUT FILTER 69 installation 4 INTERNAL DOCS 66 JAVADOC AUTOBRIEF 63 LaTeX 13 LATEX 74 LATEX CMD NAME 73 LATEX HEADER 74 LATEX HIDE INDICES 74 LATEX OUTPUT 73 LATEX PDFLATEX 74 license 2 MACRO_EXPANSION 76 make 4 MAKEINDEX CMD NAME 73 MAN LINKS 75 MAN OUTPUT 75 DOT GRAPH DEPTH 79 MAX EXTENSION 75 MAX INITIALIZER LINES 67 MSCGEN PATH 77 MULTILINE CPP IS BRIEF 64 OPTIMIZE FOR FORTRAN 65 OPTIMIZE OUTPUT 65 OPTIMIZE OUTPUT JAVA 65 OPTIMIZE OUTPUT 64 OPTIMIZE OUTPUT 65 output formats 41 OUTPUT DIRECTORY 62 OUTPUT LANGUAGE 62 PAPER TYPE 73 parsing 14 PDF HYPERLINKS 74 perl 4 PATH 77 perlmod 128 PERLMOD LATEX 76 PERLMOD_MAKEVAR PREFIX 76 PERLMOD PRETTY 76 PREDEFINED 76 PROJECT_NAME 62 PROJECT_NUMBER 62 Qt 4 QT_AUTOBRIEF 63 QUIET 67 RECURSIVE 68 70 REFERENCES _LINK_SOURCE 70 REFERENCES RELATION 70 REPEAT BRIEF 63 RTF 13 RTF HYPERLINKS 74 OUTPUT 74 RTF_STYLESHEET FILE 75 SEARCH INCLUDES 76 SEARCHENGINE 79 SEPARATE MEMBER PAGES 64 SHORT 63 SHOW DIRECTORIES 67 SHOW FILES 67 SHOW INCLUDE FILES 66 SHOW NAMESPACES 67 SHOW_USED_FILES 67 SKIP FUNCTION MACROS 77 SORT BRIEF DOCS 66 SORT BY
68. CS Ifthe INHERIT_DOCS tag is set to YES the default then an undocumented member inherits the documentation from any documented member that it re implements SEPARATE MEMBER PAGES If the SEPARATE MEMBER PAGES tag is set to YES then doxygen will produce a new page for each member If set to NO the documentation of a member will be part of the file class namespace that contains it 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 ALIASES This tag can be used to specify a number of aliases that acts as commands in the documentation An alias has the form name value For example adding sideeffect par Side Effects Mn will allow you to put the command sideeffect or sideeffect in the documentation which will result in a user defined paragraph with heading Side Effects You can put n s in the value part of an alias to insert newlines User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 65 OPTIMIZE OUTPUT FOR C Set the 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 OPTIMIZE OUTPUT JAVA Set the OPTIMIZE OUTPUT JAVA tag to YES if yo
69. CT NUMBER 1 0 doxygen If multiple options with the same name are specified then doxygen will use the last one To append to an existing option you can use the operator 18 How did doxygen get its name Doxygen got its name from playing with the words documentation and generator documentation docs gt dox generator gt gen 49 At the time I was looking into lex and yacc where a lot of things start with yy so the y slipped in and made things pronounceable the proper pronouncement is Docs ee gen so with a long e 19 What was the reason to develop doxygen I once wrote a GUI widget based on the Qt library it is still available at http qdbttabular sourceforge net and maintained by Sven Meyer Qt had nicely generated documentation using an internal tool which they didn t want to release and I wrote similar docs by hand This was a nightmare to maintain so I wanted a similar tool I looked at Doc but that just wasn t good enough it didn t support signals and slots and did not have the Qt look and feel I had grown to like so I started to write my own tool Troubleshootinh Known problems e If you have problems building doxygen from sources please read this section first 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 e
70. ECTIONS tag can be used to enable conditional documentation sections marked by Vif lt section label gt endif and cond lt section label gt endcond blocks AX_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 SHOW_USED_FILES Set the SHOW USED FILES tag to NO to disable the list of files generated at the bottom of the documentation of classes and structs If set to YES the list will mention the files that were used to generate the documentation SHOW DIRECTORIES If the sources in your project are distributed over multiple directories then setting the SHOW DIRECTORIES tag to YES will show the directory hierarchy in the documentation SHOW FILES Set the SHOW FILES tag to NO to disable the generation of the Files page This will remove the Files entry from the Quick Index and from the Folder Tree View if specified The default is YES SHOW NAMESPACES Setthe SHOW NAMESPACES tag to NO to disable the generation of the Namespaces page This will remove the Namespaces entry from the Quick Index and
71. EVAR_PREF IX This is useful so different doxyrules make files included by the same Makefile don t overwrite each other s variables 42 Preprocessor related options ENABLE PREPROCESSING If the ENABLE_PREPROCESSING 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 tag is set to YES doxygen will expand all macro names in the source code If set to NO the default only conditional compilation will be performed Macro expansion can be done in a controlled way by setting EXPAND_ONLY_PREDEF to YES EXPAND ONLY PREDEF If the EXPAND ONLY PREDEF and MACRO EXPANSION tags are both set to YES then the macro expansion is limited to the macros specified with the PREDEFINED and EXPAND AS DEFINED tags SEARCH_INCLUDES Ifthe SEARCH INCLUDES tag is set to YES the default the includes files in the INCLUDE_PATH see below will be searched if a include is found INCLUDE PATH The INCLUDE 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 PREDEFINED The PREDEFINED tag can be used to specify one or more macro names that are defined before the preprocessor is started
72. FILES SHOW NAMESPACES SHOW USED FILES SIP SUPPORT SKIP FUNCTION MACROS SORT BRIEF DOCS SORT BY SCOPE NAME SORT GROUP NAMES SORT MEMBER DOCS SOURCE BROWSER STRIP CODE COMMENTS STRIP FROM INC PATH STRIP FROM PATH SUBGROUPING SIZE TAGFILES TEMPLATE RELATIONS TOC EXPAND TREEVIEW WIDTH 29 29 31 32 33 33 33 29 37 37 37 37 42 45 29 29 30 30 30 30 30 29 42 30 30 30 30 33 33 29 29 29 29 43 44 35 35 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 62 TYPEDEF HIDES STRUCT 29 WARN_IF_UNDOCUMENTED 31 UML LOOK 44 WARN LOGFILE 31 USE HTAGS 33 WARN NO PARAMDOC 31 USE PDFLATEX 36 WARNINGS 31 USE WINDOWS ENCODING 29 XML DTD 39 VERBATIM HEADERS 33 XML OUTPUT 39 WARN FORMAT 31 XML PROGRAMLISTING 39 WARN IF DOC ERROR 31 XML SCHEMA 39 29 Project related options DOXYFILE ENCODING This tag specifies the encoding used for all characters in the config file that follow The default is UTF 8 which is also the encoding used for all text before the first occur rence of this tag Doxygen uses libiconv or the iconv built into libc for the transcoding See http www gnu org software libiconv for the list of possible encodings 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 t
73. HTML as clickable image maps and IATEX as Encapsulated PostScript images Uses the dot tool of the Graphviz tool kit to generate include dependency graphs collaboration diagrams call graphs directory structure graphs and graphical class hierarchy graphs Flexible comment placement Allows you to put documentation in the header file before the decla ration of an entity source file before the definition of an entity or in a separate file Generates a list of all members of a class including any inherited members along with their protec tion level Outputs documentation in on line format HTML and UNIX man page and off line format 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 Microsoft s HTML Help Workshop Windows only and PDF can be generated from the IATEX 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 ported References
74. INK_SOURCE If the REFERENCES_LINK_SOURCE tag is set to YES the default and SOURCE BROWSER tag is set to YES then the hyperlinks from functions in REFERENCES _ RELATION and REFERENCED B Y RELATION lists will link to the source code Otherwise they will link to the documentstion lt ERBATIM HEADERS If the VERBATIM HEADERS tag is set the YES the default then doxygen will generate a verbatim copy of the header file for each class for which an include is specified Set to NO to disable this See also Section class USE_HTAGS If the USE_HTAGS tag is set to YES then the references to source code will point to the HTML generated by the htags 1 tool instead of doxygen built in source browser The htags tool is part of GNU s global source tagging system see http www gnu org software global global html The use it do the following 1 Install the latest version of global i e 4 8 6 or better 2 Enable SOURCE BROWSER and USE HTAGS in the config file 3 Make sure the INPUT points to the root of the source tree 4 Run doxygen as normal Doxygen will invoke htags and that will in turn invoke gtags so these tools must be available from the command line i e in the search path The result instead of the source browser generated by doxygen the links to source code will now point to the output of htags 34 Alphabetical index options ALPHABETICAL INDEX
75. ION GRAPH 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 and 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 if CALL GRAPH is set to YES a graphical call graph is drawn for each function showing the functions that the function directly or indirectly calls if CALLER GRAPH is set to YES a graphical caller graph is drawn for each function showing the functions that the function is directly or indirectly called by The elements in the class diagrams in HTML and RTF have the following meaning e A yellow box indicates a class A box can have a little marker in the lower right corner to indicate 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 e A white box indicates that the documentation of the class is currently shown e A grey box indicates an undocumented class A solid dark blue arrow indicates public inheritance A dashed dark green arrow indicates protected inheritance User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 33 A dotted dark green arrow indicates private inheritance The elements in the class diagram
76. IVE 69 EXCLUDE 68 EXCLUDE PATTERNS 69 EXCLUDE SYMLINKS 68 EXPAND 5 DEFINED 76 EXPAND ONLY PREDEF 76 EXTERNAL GROUPS 77 EXTRA PACKAGES 74 EXTRACT ALL 65 EXTRACT ANON NSPACES 65 EXTRACT LOCAL CLASSES 65 EXTRACT LOCAL METHODS 65 EXTRACT PRIVATE 65 EXTRACT STATIC 65 features 50 PATTERNS 68 FILTER 68 FILTER_PATTERNS 69 FILTER SOURCE FILES 69 flex 4 FORMULA FONTSIZE 73 FULL PATH NAMES 63 GENERATE AUTOGEN DEF 76 GENERATE BUGLIST 67 GENERATE CHI 72 GENERATE DEPRECATEDLIST 66 GENERATE DOCSET 72 GENERATE HTML 70 GENERATE HTMLHELP 72 GENERATE LATEX 73 GENERATE LEGEND 79 GENERATE MAN 75 GENERATE PERLMOD 76 GENERATE 74 GENERATE TAGFILE 77 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 INDEX 138 GENERATE_TESTLIST 67 GENERATE_TODOLIST 66 GENERATE_TREEVIEW 73 GENERATE_XML 75 GPL 2 GRAPHICAL HIERARCHY 79 GROUP_GRAPHS 78 HAVE DOT 78 HHC LOCATION 72 HIDE FRIEND COMPOUNDS 66 HIDE IN BODY DOCS 66 HIDE SCOPE NAMES 66 HIDE UNDOC CLASSES 66 HIDE UNDOC MEMBERS 66 HIDE RELATIONS 78 HTML ALIGN MEMBERS 72 HTML DYNAMIC SECTIONS 72 HTML FILE EXTENSION 71 HTML FOOTER 71 HTML HEADER 71 HTML OUTPUT 71 HTML STYLESHEET 71 IDL PROPERTY SUPPORT 64 IGNORE PREFIX 70 IMAGE PATH 69 INCLUDE_GRAPH 78 INCLUDE_PATH 76 INCLUDED BY GRAPH 78 INHERIT DO
77. Implementation public Intf public void func cond TEST void test endcond cond This method is obsolete and does not show up in the documentation void obsolete endcond endcond The output will be different depending on whether or not ENABLED_SECTIONS contains TEST or DEV 86 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 87 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 88 details detailed decription Just like brief starts a brief description details starts the detailed description You can also start a new paragraph blank line then the details command is not needed 89 else Starts a conditional section if the previous conditional section was not enabled The previous section should have been started with a if if
78. JAVADOC AUTOBRIEF set to YES test class A more elaborate class description class Test public An enum More detailed enum description enum TEnum TVall lt enum value TVall x TVal2 lt enum value TVal2 x TVal3 lt enum value TVal3 x xenumPtr lt enum pointer Details enumVar x lt enum variable Details constructor A more elaborate description of the constructor Test destructor A more elaborate description of the destructor User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 19 Test normal member taking two arguments and returning integer value param a an integer argument param s a constant character pointer see Test see Test see testMeToo see publicVar return The test results F int testMe int a const char 5 A pure virtual member see testMe param cl the first argument param c2 the second argument virtual void testMeToo char cl char c2 0 public variable Details int publicVar a function variable Details x int xhandler int a int Similarly if one wishes the first sentence of a Qt style documentation block to automatically be treated as a brief description one may set
79. KK MACRO EXPANSION YES EXPAND ONLY PREDEF YES SEARCH INCLUDES YES FULL PATH NAMES YES STRIP FROM PATH QTDIR PREDEFINED USE TEMPLATECLASS Q EXPORT ArrayT QArray ListT QList DictT QDict QueueT QQueue VectorT QVector PtrDictT QPtrDict IntDictT QIntDict StackT QStack DictIteratorT QDictIterator ListIteratorT QListIterator CacheT QCache CacheIteratorT QCacheIterator ntCacheT QIntCache ntCacheIteratorT QIntCacheIterator User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 QIntDictIteratorT QIntDictIterator QPtrDictIteratorT QPtrDictIterator OTDIR doc QTDIR src widgets QTDIR src kernel INPUT QTDIR src dialogs QTDIR src tools FILE PATTERNS cpp h q doc INCLUDE_PATH QTDIR include RECURSIVE YES For the Qt 2 1 sources I recommend to use the following settings PROJECT_NAME Qt PROJECT_NUMBER 2 1 HIDE_UNDOC_MEMBERS YES HIDE_UNDOC_CLASSES YES SOURCE_BROWSER YES INPUT S 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 0 ENABLE PREPROCESSING YES MACRO EXPANSION YES INCLUDE PATH QTDIR include PREDEFINED Q_PROPERTY x Q_OVERRIDE x Q_EXPORT Q_ENUMS x OT STATIC CONST static const
80. LUDED 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 CALL GRAPH Ifthe CALL GRAPH and HAVE DOT tags are set to YES then doxygen will generate a call dependency graph for every global function or class method Note that enabling this option will significantly increase the time of a run So in most cases it will be better to enable call graphs for selected functions only using the callgraph command User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 79 CALLER GRAPH If the CALLER GRAPH and HAVE_DOT tags are set to YES then doxygen will generate a caller dependency graph for every global function or class method Note that enabling this option will significantly increase the time of a run So in most cases it will be better to enable caller graphs for selected functions only using the callergraph command 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 DIRECTORY GRAPH If the DIRECTORY GRAPH SHOW DIRECTORIES and HAVE options setto YES then doxygen will show the dependencies a directory has on other directories in a graphical way The dependency relations are determined by the include rela
81. LaTeX related options 37 RTF related options 38 Man page related options 39 XML related options 40 AUTOGEN DEF related options 41 PERLMOD related options 42 Preprocessor related options 43 External reference options 39 40 41 42 42 43 50 59 62 65 67 68 69 70 70 73 74 75 75 76 76 76 77 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 44 Dot options 45 Search engine options 46 Introduction 47 addtogroup lt name gt title 48 callgraph 49 callergraph 50 category lt name gt lt header file gt lt header name gt 51 class lt name gt lt header file gt lt header name gt 52 def lt name gt 53 defgroup lt name gt group title 54 dir lt path fragment gt 55 enum lt name gt 56 example lt file name gt 57 file lt name gt 58 fn function declaration 59 headerfile lt header file gt lt header name gt 60 hideinitializer 61 ingroup lt groupname gt lt groupname gt lt groupname gt 62 interface lt name gt lt header file gt lt header name gt 63 internal 64 mainpage title 65 name header 66 namespace lt name gt 77 79 81 84 84 84 85 85 85 86 86 86 87 87 88 88 89 89 89 89 89 90 90 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENT
82. Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 76 40 AUTOGEN DEF related options GENERATE_AUTOGEN_DEF Ifthe GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will generate an AutoGen Definitions see http autogen sf net file that captures the structure of the code including all documentation Note that this feature is still experimental and incomplete at the moment 41 PERLMOD related options GENERATE PERLMOD If the GENERATE PERLMOD tag is set to YES Doxygen will generate a Perl mod ule file that captures the structure of the code including all documentation Note that this feature is still experimental and incomplete at the moment PERLMOD_LATEX Ifthe PERLMOD LATEX tag is set to YES Doxygen will generate the necessary Make file rules Perl scripts and LaTeX code to be able to generate PDF and DVI output from the Perl module output PERLMOD PRETTY If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely formatted so it can be parsed by a human reader This is useful if you want to understand what is going on On the other hand if this tag is set to NO the size of the Perl module output will be much smaller and Perl will parse it just the same PERLMOD_MAKEVAR_PREFIX The names of the make variables in the generated doxyrules make file are prefixed with the string contained in PERLMOD_MAK
83. NABLE PREPROCESSING ENUM VALUES PER LINE ENABLED SECTIONS EXAMPLE PATH EXAMPLE PATTERNS EXAMPLE RECURSIVE EXCLUDE EXCLUDE PATTERNS EXCLUDE SYMLINKS EXPAND 5 DEFINED EXPAND ONLY PREDEF EXTERNAL GROUPS EXTRA PACKAGES EXTRACT ALL EXTRACT ANON NSPACES EXTRACT LOCAL CLASSES EXTRACT LOCAL METHODS EXTRACT PRIVATE EXTRACT STATIC FILE PATTERNS FILE_VERSION_FILTER FILTER PATTERNS FILTER SOURCE FILES FORMULA FONTSIZE FULL PATH NAMES GENERATE AUTOGEN DEF 35 35 44 44 44 44 d 44 44 44 29 42 35 30 32 32 32 32 32 32 42 42 43 36 30 30 30 30 30 30 32 32 32 32 95 29 40 GENERATE_BUGLIST GENERATE CHI GENERATE DEPRECIATEDLIST GENERATE DOCSET GENERATE HTML GENERATE HTMLHELP GENERATE LATEX GENERATE LEGEND GENERATE MAN GENERATE PERLMOD GENERATE RTF GENERATE TAGFILE GENERATE TESTLIST GENERATE TODOLIST GENERATE TREEVIEW GENERATE XML GRAPHICAL HIERARCHY GROUP GRAPHS HAVE DOT HHC LOCATION HIDE FRIEND COMPOUNDS BODY DOCS HIDE SCOPE NAMES HIDE UNDOC CLASSES HIDE UNDOC MEMBERS HIDE UNDOC RELATIONS HTML ALIGN MEMBERS HTML DYNAMIC SECTIONS HTML FOOTER HTML HEADER HTML OUTPUT HTML STYLESHEET IDL PROPERTY SUPPORT IGNORE PREFIX IMAGE PATH INCLUDE GRAPH INCLUDE PATH 30 35 30
84. NPUT source files This way you can easily exclude a subdirectory from a directory tree whose root is specified with the INPUT tag EXCLUDE SYMLINKS The EXCLUDE_SYMLINKS tag can be used select whether or not files or directo ries that are symbolic links a Unix filesystem feature are excluded from the input User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 69 EXCLUD PATTI E PATTERNS Ifthe value of the INPUT tag contains directories you can use the EXCLUDE_ ries ERNS tag to specify one or more wildcard patterns to exclude certain files from those directo Note that the wildcards are matched against the file with absolute path so to exclude all test directo ries use the pattern test EXAMP E PATH The EXAMP E RECURS I VI value of the RI EXAMPL E PATTERNS If the value of the EXAMPLE PATT ECURSIVI E If the EXAMPLE RECUR E tag Possible values are Y EXAMPLE 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 SIVE tag is set to YES then subdirectories will be searched for input files to be used with the include or dontinclude commands irrespective of the ES and NO If left blank NO is used
85. RATE flag controls if a separate chi index file is generated YES or that it should be included in the master chm file NO 1 BINARY TOC Ifthe GENERATE HTMLHELP tag is set to YES the BINARY_TOC flag controls whether a binary table of contents is generated YES or a normal table of contents NO in the chm file TOC 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 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 73 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 TR EEVIEW The GENERATE TREEVIEW tag is used to specify whether a tree like index structure should be generated to display hierarchical information If the tag value is set to FRAME a side panel will be generated containing a tree like index structur
86. RMAT 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 68 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 32 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 If this tag is empty the current directory is searched INPUT ENCODING This tag can be used to specify the character encoding of the source files that doxy gen parses Internally doxygen uses the UTF 8 encoding which is also the default input encod ing Doxygen uses libiconv or the iconv built into libc for the transcoding See the 1 documentation for the list of possible encodings FILE PATTERNS If the value of the INPUT tag contains directories you can use the FILE PATTERNS tag to specify one or more wildcard patterns like and h to filter out the source files in the directories If left blank the following pattern
87. RTY SUPPORT For Microsoft s IDL there are propget and propput attributes to indicate get ter and setter methods for a property Setting this option to YES the default will make doxygen to replace the get and set methods by a property in the documentation This will only work if the methods are indeed getting or setting a simple type If this is not the case or you want to show the methods anyway you should set this option to NO DISTRIBUTE GROUP DOC If member grouping is used in the documentation and the DISTRIBUTE GROUP tag is set to YES then doxygen will reuse the documentation of the first member in the group if any for the other members of the group By default all members of a group must be documented explicitly MULTILINE CPP IS BRIEF The MULTILINE CPP 15 BRIEF tag can be set to YES to make Doxy gen treat a multi line C special comment block i e a block of or comments as a brief description This used to be the default behaviour The new default is to treat a multi line C com ment block as a detailed description Set this tag to YES if you prefer the old behaviour instead Note that setting this tag to YES also means that rational rose comments are not recognized any more DETAILS_AT_TOP If the DETAILS AT TOP tag is set to YES then Doxygen will output the detailed description near the top like JavaDoc If set to NO the detailed description appears after the member documentation INHERIT DO
88. S 67 nosubgrouping 68 overload function declaration 69 package lt name gt 70 page lt name gt title 71 property qualified property name 72 protocol lt name gt lt header file gt lt header name gt 73 relates lt name gt 74 relatesalso lt name gt 75 showinitializer 76 struct lt name gt lt header file gt lt header name gt 77 typedef typedef declaration 78 union lt name gt lt header file gt lt header name gt 79 var variable declaration 80 weakgroup lt name gt title 81 attention attention text 82 author list of authors 83 brief brief description 84 bug bug description 85 cond lt section label gt 86 date date description 87 deprecated description 88 details detailed decription 89 else 90 90 91 91 92 92 92 93 93 93 93 93 94 94 94 94 95 95 95 96 96 96 96 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 90 elseif lt section label gt 91 endcond 92 endif 93 exception lt exception object gt exception description 94 if lt section label gt 95 ifnot lt section label gt 96 invariant description of invariant 97 note text 98 par paragraph title paragraph 99 param lt parameter name gt parameter description 100 tparam lt template parameter name gt description 101
89. SCOPE 66 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 INDEX 139 SORT_GROUP_NAMES 66 SORT_MEMBER_DOCS 66 SOURCE_BROWSER 69 strip 4 STRIP CODE COMMENTS 69 STRIP FROM INC PATH 63 STRIP FROM PATH 63 SUBGROUPING 65 TAB SIZE 64 TAGFILES 77 TEMPLATE RELATIONS 78 TOC EXPAND 72 TREEVIEW WIDTH 73 TYPEDEF HIDES STRUCT 65 UML 78 USE_HTAGS 70 USE WINDOWS ENCODING 62 VERBATIM HEADERS 70 WARN FORMAT 67 WARN IF DOC ERROR 67 WARN IF UNDOCUMENTED 67 WARN LOGFILE 68 WARN NO PARAMDOC 67 WARNINGS 67 XML 13 XML_DTD 75 XML_OUTPUT 75 XML_PROGRAMLISTING 75 XML_SCHEMA 75 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006
90. Since it is 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 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 included in the documentation are replaced by links for instance when using SOURCE_BROWSER YES and links to overloaded members may point to the wrong member This also holds for the Referenced by list that is genera
91. SomeClass for more information which would be the same as writing See Nref SomeClass for more information Note that you can overload an alias by a version with multiple arguments for instance ALIASES 1 1 ref M ALIASES 1 2 ref 1 2 Note that the quotes inside the alias definition have to be escaped with a backslash With these alias definitions we can write See Nl SomeClass Some Text for more information inside the comment block and it will expand to See ref SomeClass Some Text for more information User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 43 where the command with a single argument would still work as shown before Aliases can also be expressed in terms of other aliases e g a new command reminder can be expressed as a xrefitem via an intermediate xreflist command as follows ALIASES xreflist 3 xrefitem 1 2 3 N ALIASES reminder xreflist reminders Reminder Reminders Note that if for aliases with more than one argument a comma is used as a separator if you want to put a comma inside the command you will need to escape it with a backslash i e l SomeClass Some text with an escaped comma given the alias definition of M in the example above 27 Nesting custom command You can use commands as arguments of aliases including commands defined using aliases As an example consider the followi
92. TE2 class name idl id2 id3 id4 id5 id6 id7 id8 id9 1410 1411 As you can see doxygen s preprocessor is quite powerful but if you want even more flexibility you can always write an input filter and specify it after 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 and WARNINGS NO in the configuration file to disable any other output Automatic link generationMost 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 the documentation For TEX documentation a reference to the page number is written instead of a link Furthermore the index at the end of the document can be 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 18 Links to web pages and mail addresses Doxygen will automatically replace any URLs and mail addresses found in the documentation by links in HTML 19 Links to classes All words in the documentatio
93. a protected member variable of Test Test var A link to the global enumeration type GlobEnum A link to the define ABS x A link to the destructor of the Test class Test Test A link to the typedef B A link to the enumeration type Test EType A link to some enumeration values Test Vall and GVal2 x 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 f Test and Test A link to a member in this class member More specific links to the each of the overloaded members member int and member int int A link to the variable var A link to the global typedef B 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 xf class Test User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 public Test lt constructor Test 1 lt destructor void member int lt A member function Details void member int int lt An o
94. aight e amp 1squo left single quotation mark e amp rsquo right single quotation mark e amp ldquo left double quotation mark e amp rdquo right double quotation mark e amp ndash n dash for numeric ranges eg 2 8 e amp mdash m dash for parenthetical punctuation like this e amp uml1 where is one of A E LO U Y a e i o u y writes a character with a diaeresis accent like a e amp acute where is one of A E I 0 U Y a e i 0 u y writes a character with a acute accent like e amp grave where is one of A E 0 U a i 0 u y writes a character with a grave accent like a e amp circ where is one of A E I 0 U a e i 0 u y writes a character with a circumflex accent like e amp tilde where is one of A N O a n o writes a character with a tilde accent like 4 e amp szlig write a sharp s i e to the output e amp cedil where is one of c C writes a c cedille like e amp ring where is one of a A writes an a with a ring like e amp nbsp anon breakable space Finally to put invisible comments inside comment blocks HTML style comments can be used lt This is a comment with a comment block Visible text x XML commandsDoxygen supports most of the XML commands that are typically used in C code com ments The XML tags are defined in Appendix E of the ECMA 334 standard which defines the C language Unfo
95. ain at least a lt BODY gt and a lt HTML gt tag A minimal example BODY HTML If the tag is left blank doxygen will generate a standard footer The following commands have a special meaning inside the footer title datetime date doxygenversion projectname projectnumber Doxygen will replace them by re 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 footer that doxygen normally uses 1 I HTML STYLESHEET The HTML STYLESHEET tag can 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 also section Doxygen usage for information on how to generate the style sheet that doxygen normally uses User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 72 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 inten
96. alphabetical order If set to NO the default the group names will appear in their defined order SORT_BY_SCOPE_NAME Ifthe SORT_BY_SCOPE_NAME tag is set to YES the class list will be sorted by fully qualified names including namespaces If set to NO the default the class list will be sorted only by class name not including the namespace part Note This option is not very useful if HIDE_SCOPE_NAMES is set to YES This option applies only to the class list not to the alphabetical list GENERATE DEPRECATEDLIST The GENERATE DEPRECATEDLIST tag can be used to enable YES or disable NO the deprecated list This list is created by putting deprecated commands in the documentation 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 67 GENERATE TESTLIST GENERATE TESTLIST tag can be used to enable YES or disable NO the test list This list is created by putting Mest 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 ENABLED SECTIONS The ENABLED S
97. arly a case where the fn command is redundant and will only lead to problems User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 23 13 Special documentation blocks in Python For Python there is a standard way of documenting the code using so called documentation strings Such strings are stored in doc and can be retrieved at runtime Doxygen will extract such comments and assume they have to be represented in a preformatted way docstring Documentation for this module More details func Documentation for a function More details pass class PyClass Documentation for a class More details def __init__ self The constructor self memVar 0 def PyMethod self Documentation for a method pass Note that in this case none of doxygen s special commands are supported There is also another way to document Python code using comments that start with HP These type of comment blocks are more in line with the way documentation blocks work for the other languages supported by doxygen and this also allows the use of special commands Here is the same example again but now using doxygen style comments package pyexample Documentation for this module More details Documentation for a function More details def func pass Documentation for a class More details class PyClass The con
98. ave to put quotes 7 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 on a single line and 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 height The size should be a valid size specifier in IXIEX 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 x image html application jpg x image latex application eps My application width 10cm And this is an 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 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 162 latexonly Starts a block of text that will be verbatim included in the generated documentation only The block ends with a endlatexonly command This comman
99. clude lt file name gt 134 a lt word gt 135 arg item description 102 102 103 103 103 103 104 104 105 105 105 105 106 106 107 107 107 107 108 108 108 108 109 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 136 b lt word gt 137 c lt word gt 138 code 139 lt link object gt 140 copybrief lt link object gt 141 copydetails lt link object gt 142 dot 143 msc 144 dotfile lt file gt caption 145 e lt word gt 146 em lt word gt 147 endcode 148 enddot 149 endmsc 150 endhtmlonly 151 endlatexonly 152 endmanonly 153 endverbatim 154 endxmlonly 155 f 156 1 15711 158 f environment 109 109 110 110 110 110 110 111 112 112 112 113 113 113 113 113 113 113 114 114 114 114 114 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 159 f 160 htmlonly 161 image lt format gt lt file gt caption lt sizeindication gt lt size gt 162 latexonly 163 manonly 164 li item description 165 n 166 p lt word gt 167 verbatim 168 xmlonly 169 170 171 Languageld 172 6 173 174 175 lt 176 gt 177 96 178PHP only commands Developers Manual 179Using the Perl Module output format 180Using the Perl Module based LaTeX generator 114 114
100. cumentation at other places to learn more about structural commands Files can only be documented using the second option since there is no way to put a documentation block before a file Of course file members functions variable typedefs defines do not need an explicit structural command just putting a special documentation block in front or behind them will do The text inside a special documentation block is parsed before it is written to the HTML and or 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 Ifa line starts with some whitespace followed by one or more asterisks and then optionally more whitespace then all whitespace and asterisks are removed 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 unless the word is preceded by a 26 then the word will not be linked and the sign is removed 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 in the documentation are interpreted and converted to equivalents for the IATEX outp
101. d can be used to include TFX 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 116 Note environment variables like HOME are resolved inside a IATEX only block See also section latexonly and section htmlonly 163 manonly Starts a block of text that will be verbatim included in the generated MAN documentation only The block ends with a endmanonly command This command can be used to include groff code directly into MAN pages You can use the htmlonly and Matexonly and endhtmlonly and endlatexonly pairs to provide proper HTML and alternatives See also section htmlonly and section latexonly 164 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 Mi command Example Typing li Nc AlignLeft left alignment li Nc AlignCenter center alignment li Nc 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
102. d 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 54 dir lt path fragment gt Indicates that a comment block contains documentation for a directory The path fragment argument should include the directory name and enough of the path to be unique w r t the other directories in the project The SHOW DIRECTORIES option determines whether or not the directory information is shown and the option determines what is stripped from the full path before it appears in the output 55 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 venum 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 Jj Another enum with inline docs enum AnotherEnum V1 lt value 1 V2 x lt value 2 1 class Test The class description
103. ded using the pattern 5 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 INCLUDE_PATH my_config_dir The configuration options can be divided into several categories Below is an alphabetical index of the tags that are recognized followed by the descriptions of the tags grouped by category ABBREVIATE_BRIEF 29 CLASS_DIAGRAMS 44 ALIASES 29 CLASS_GRAPH 44 ALLEXTERNALS 43 COLLABORATION GRAPH 44 ALPHABETICAL INDEX 34 COLS IN ALPHA INDEX 34 ALWAYS_DETAILED_SEC 29 COMPACT_LATEX 36 35 COMPACT 37 BUILTIN STL SUPPORT 29 CPP CLI SUPPORT 29 BRIEF MEMBER DESC 29 CREATE SUBDIRS 29 CALL GRAPH 44 DETAILS_AT_TOP 29 CALLER_GRAPH 44 DIRECTORY GRAPH 44 CASE SENSE NAMES 29 DISABLE INDEX 35 CHM FILE 35 DISTRIBUTE GROUP DOC 29 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 60 DOCSET BUNDLE ID DOCSET FEEDNAME DOT FONTNAME DOT FONTPATH DOT GRAPH MAX NODES DOT IMAGE FORMAT DOT MULTI TARGETS DOT PATH DOT TRANSPARENT DOTFILE DIRS DOXYFILE ENCODING E
104. documentation of a non member function lt name gt It puts the function both inside the related function section of the class documentation as well as leaving its normal file doc umentation location This command is useful for documenting non friend functions that are nevertheless strongly coupled to a certain class It only works for functions 75 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 76 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 77 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 78 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 94 79 var variable declaration
105. e then you should according to Anke Selig edit ce parse cpp and replace extern C void 11 unsigned int with include lt alloca h gt If that does not help try removing ce_parse cpp and let bison rebuild it this worked for me If you are compiling for Digital Unix the same problem can be solved according to Barnard Schmallhof by replacing the following in ce parse cpp else not GNU C if defined STDC amp amp defined sparc defined sparc defined __sparc defined 501 include lt alloca h gt with else not GNU C if defined __STDC__ amp amp defined sparc defined __sparc__ defined __sparc defined __sgi defined __osf__ include lt alloca h gt Alternatively one could fix the problem at the bison side Here is patch for bison simple provided by Andre Johansen bison simple Tue Nov 18 11 45 53 1997 bison simple Mon Jan 26 15 10 26 1998 27 7 27 7 ifdef GNUC define alloca builtin alloca else not GNU C if defined STDC amp amp defined sparc defined sparc defined sparc defined sgi if defined STDC amp amp defined sparc defined __sparc__ defined __sparc defined sgi defined alpha include alloca h else not sparc x if defined MSDOS amp amp defined __TURBOC__ The generated scanner cpp
106. e elseif em endcode endcond enddot endhtmlonly 134 115 47 116 135 81 82 136 83 84 137 48 49 50 51 138 85 140 141 139 86 52 53 87 88 54 125 142 144 145 89 90 146 147 91 148 150 endif endlatexonly endlink endmanonly endmse endverbatim endxmlonly enum example exception f MI M Mile Mn headerfile hideinitializer htmlinclude htmlonly vif ifnot image include includelineno ingroup internal invariant interface latexonly Vi Mine link mainpage manonly Wnsc 92 151 117 152 149 153 154 55 56 93 155 156 157 158 159 57 58 59 60 133 160 94 95 161 126 127 61 63 96 62 162 164 128 118 64 163 143 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 n 165 showinitializer 75 name 65 since 108 66 skip 129 nosubgrouping 67 skipline 130 note 97 struct 76 overload 68 subpage 120 p 166 subsection 122 package 69 subsubsection 123 page 70 test 109 98 throw 110 paragraph 124 todo t 100 param 99 tparam typedef 77 post 101 typ union 78 pre until 131 private PHP only 178 War 79 privatesection PHP only 178 Werbatim 167 property 71 verbinclude 132 protected
107. e O2 for the particular files in the Makefile versions before 2 95 may produce broken binaries due to bugs in these compilers Dot problems Due to a change in the way image maps are generated older versions of doxygen lt 1 2 17 will not work correctly with newer versions of graphviz gt 1 8 8 The effect of this incompatibility is that generated graphs in HTML are not properly clickable For doxygen 1 3 it is recommended to use at least graphviz 1 8 10 or higher For doxygen 1 4 7 or higher it is recommended to use GraphViz 2 8 or higher to avoid font issues Red Hat 9 0 problems If you get the following error after running make tmake error qtools pro 70 Syntax error then first type export LANG before running make 4 Compiling from source on Windows From version 1 5 0 onwards build files are provided for Visual Studio 2005 Also the free as in beer Express version of Developer Studio can be used to compile doxygen Alternatively you can compile doxygen the Unix way using Cygwin or MinGW Before you can compile doxygen you need to download and install the C compiler of Visual Studio Since Microsoft apparently wants to lure everyone into using their NET stuff they made things somewhat difficult when you use the Express version You need to do some manual steps in order to setup a proper working environment for building native win32 applications such as Doxygen The next step is to install unxutils see
108. e just like the one that is gen erated for HTML Help For this to work a browser that supports JavaScript DHTML CSS and frames is required for instance Mozilla 1 0 Netscape 6 0 Internet explorer 5 0 or Konqueror Windows users are probably better off using the HTML help feature Other possible values for this tag are HIERARCHIES which will generate the Groups Directories and Class Hiererachy pages using a tree view instead of an ordered list ALL which combines the behavior of FRAME and HIERARCHIES and NONE which disables this behavior completely For backwards compatibility with previous releases of Doxygen the values YES and NO are equivalent to FRAME and NONE respectively Via custom stylesheets see HTML STYLESHEET one can further fine tune the look of the index As an example the default style sheet generated by doxygen has an example that shows how to put an image at the root of the tree instead of the project name TRE FOR EVIEW_WIDTH If the treeview is enabled see GENERATE TREEVIEW then this tag can be used to set the initial width in pixels of the frame in which the tree is shown ULA FONTSIZE Use this tag to change the font size of Latex formulas included as images in the HTML documentation The default is 10 when you change the font size after a successful doxygen run you need to manually remove any form png images from the HTML output di
109. e shape record fontname Helvetica fontsize 10 b label class B URL ref B c label class C URL ref C b gt arrowhead open style dashed enddot Note that the classes in the above graph are clickable in the HTML output 143 msc Starts a text fragment which should contain a valid description of a message sequence chart See http www mcternan me uk mscgen for examples The text fragment ends with endmsc Note The text fragment should only include the part of the message sequence chart that is within the msc block You need to install the mscgen tool if you want to use this command Here is an example of the use of the msc command x Sender class Can be used to send a command to the server The receiver will acknowlegde the command by calling Ack msc Sender Receiver Sender gt Receiver label Command URL ref Receiver Command Sender Receiver label Ack URL ref Ack ID 1 endmsc x class Sender public Acknowledgement from server x void Ack bool ok i Receiver class Can be used to receive and execute commands After execution of a command the receiver will send an acknowledgement msc Receiver Sender Receiver Sender label Command URL ref Command Receiver Sender label Ack URL ref Sender Ack ID 1 Nendmsc class Receiver User Manual for Doxygen 1 5 6 written by Dimitri van
110. e Try Nauthor Bill Gates Nauthor Several species of small furry animals gathered together in a cave and grooving with a pict Nversion 4 0 x date 1996 1998 It crashes a lot and requires huge amounts of memory bug The class introduces the more bugs the longer it is used Nwarning This class may explode in your face Nwarning If you inherit anything from this class you re doomed class WindowsNT User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 95 83 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 84 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
111. e adjacent post commands will be joined 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 102 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 103 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 101 104 return description of the return value
112. e 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 3 Known compilation problems for Unix Qt problems The Qt include files and libraries are not a subdirectory of the directory pointed to by QTDIR on some systems for instance on Red Hat 6 0 includes are in usr include qt and libs are in usr lib The solution go to the root of the doxygen distribution and do mkdir qt cd qt ln s your qt include dir here include ln s your qt lib dir here lib export QTDIR SPWD If you have a csh like shell you should use setenv QTDIR PWD instead of the export command above Now install doxygen as described above Bison problems Versions 1 31 to 1 34 of bison contain a bug that results in a compiler errors like this ce parse cpp 348 member class CPPValue yyalloc yyvs with constructor not allowed in union This problem has been solved in version 1 35 versions before 1 31 will also work Latex problems The file a4wide sty is not available for all distributions If your distribution does not have it please select another paper type in the config file see the PAPER TYPE tag in the config file User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 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 cod
113. e only wants to put a brief description after a member This is done as follows int var lt Brief description after the member or int var lt Brief description after the member Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the 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 documentation block cannot be put after the enum enum EnumType int EVall lt enum value 1 x int EVal2 lt enum value 2 x void member 1 lt a member function protected int value an integer value i 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 next section like class are ignored inside these comment blocks 12 Documentation at other places So far we have assumed that the documentation blocks are always located in front of the declaration or definition of a file class or namespace or in front or after one of its members Although this is often comfortable there may sometimes be reasons to put the documentation somewhere else For documenting a file this is even required s
114. e text here HF F FF HF H OF S Note In this case the indentation is not important Using arg or Gli For compatibility with the Troll Tech s internal documentation tool and with KDoc doxygen has two commands that can be used to create simple unnested lists See arg and Mi for more info GroupingDoxygen has three 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 second mechanism works within a member list of some compound entity and is refered to as a member groups For pages there is a third grouping mechanism referred to as subpaging 15 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 The second argument is the name or title of the group as it should appear in the documentation You can make an entity a member of a specific group by putting a ingroup command inside its documen tation block User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 27 To avoid
115. e version 1 2 18 Doxygen can generate a new output format we have called the Perl Module output format It has been designed as an intermediate format that can be used to generate new and customized output without having to modify the Doxygen source Therefore its purpose is similar to the XML output format that can be also generated by Doxygen The XML output format is more standard but the Perl Module output format is possibly simpler and easier to use The Perl Module output format is still experimental at the moment and could be changed in incompatible ways in future versions although this should not be very probable It is also lacking some features of other Doxygen backends However it can be already used to generate useful output as shown by the Perl Module based LaTeX generator Please report any bugs or problems you find in the Perl Module backend or the Perl Module based LaTeX generator to the doxygen develop mailing list Suggestions are welcome as well 179 Using the Perl Module output format When the GENERATE PERLMOD tag is enabled in the Doxyfile running Doxygen generates a number of files in the perlmod subdirectory of your output directory These files are the following DoxyDocs pm This is the Perl module that actually contains the documentation in the Perl Module format described below DoxyModel pm This Perl module describes the structure of DoxyDocs pm independently of the actual documentation See below for deta
116. ectory These files contain the Perl scripts and LaTeX code necessary to generate PDF and DVI output from the Perl Module output using PDFLaTeX and LaTeX respectively Rules to automate the use of these files are also added to doxyrules make and the Makefile The additional generated files are the following e doxylatex pl This Perl script uses DoxyDocs pm and DoxyModel pm to generate doxydocs tex a TeX file containing the documentation in a format that can be accessed by LaTeX code This file is not directly LaTeXable e doxyformat tex This file contains the LaTeX code that transforms the documentation from doxy docs tex into LaTeX text suitable to be LaTeX ed and presented to the user doxylatex template pl This Perl script uses DoxyModel pm to generate doxytemplate tex a TeX file defining default values for some macros doxytemplate tex is included by doxyformat tex to avoid the need of explicitly defining some macros doxylatex tex This is a very simple LaTeX document that loads some packages and includes doxy format tex and doxydocs tex This document is LaTeX ed to produce the PDF and DVI documenta tion by the rules added to doxyrules make 180 1 Simple creation of PDF and DVI output using the Perl Module based LaTeX generator To try this you need to have installed LaTeX PDFLaTeX and the packages used by doxylatex tex 1 Update your Doxyfile to the latest version using doxygen u Doxyfile 2 Set both GENERATE PERLMOD
117. ed alphabetically Afrikaans Arabic Brazil ian Portuguese Catalan Chinese Chinese Traditional Croatian Czech Danish Dutch English Finnish French German Greek Hungarian Indonesian Italian Japanese En Korean En Lithuanian Mace donian Norwegian Persian Polish Portuguese Romanian Russian Serbian Slovak Slovene Spanish Swedish and Ukrainian 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 5 6 written by Dimitri van Heesch 1997 2006 131 Language Maintainer Contact address Status Afrikaans Johan Prinsloo johan zippysnoek com 1 4 6 Arabic Moaz Reyad moazreyad yahoo com 1 4 6 Brazilian Portuguese Fabio FJTC Jun Takada Chino 5 5 256221 con 5 up to date Catalan Maximiliano Pin max pin bitroit com 1 5 4 Albert Mora amora iua upf es Chinese Li Daobing lidaobing gmail com up to date Wei Liu liuwei asiainfo com Chinese Traditional Daniel YC Lin dlin twegmail com up to date Gary Lee garywlee gmail com Croatian Boris Bralo boris bralo zg htnet hr up to date Czech Petr P ikryl prikrylp skil cz up to date Danish Erik S e S rensen eriksoe doxygen daimi au dk 1 5 4 Dutch Dimitri
118. en generate the HTML documentation 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 You will need the python interpreter for this 5 Optional Generate a PDF version of the manual you will need pdflatex makeindex and egrep for this make pdf The PDF manual doxygen manual pdf will be located in the latex directory of the distribution Just view and print it via the acrobat reader User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 2 Installing the binaries on Unix After the compilation of the source code doamake install to install doxygen If you downloaded the binary distribution for Unix type configure make install Binaries are installed into the directory lt prefix gt bin Use make install docs to install the documentation and examples into lt docdir gt doxygen prefix defaults to usr local but can be changed with the option of the configure script The default lt docdir gt directory is lt prefix gt share doc packages and can be changed with the docdir option of the configure script Alternatively you can also copy the binaries from the bin directory manually to some bin directory in your search path This is sufficient to use doxygen Note You need the GNU install tool for this to work it is part of the coreutils package Other install tools may put th
119. ender proper text labels For formulas or if you do not wish to use pdflatex the ghostscript interpreter is needed You can find it at www ghostscript com In order to generate doxygen s own documentation Python is needed you can find it at www python org Compilation is now done by performing the following steps User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 1 Unpack the archive unless you already have done that gunzip doxygen SVERSION src tar gz uncompress the archive tar xf doxygen VERSION src tar 4 unpack it 2 Run the configure script sh configure The script tries to determine the platform you use the make tool which must be GNU make and the perl interpreter It will report what it finds To override the auto detected platform and compiler you can run configure as follows configure platform platform type See the PLATFORMS file for a list of possible platform options If you have Qt 3 3 x installed and want to build the GUI front end you should run the configure script with the with doxywizard option configure with doxywizard For an overview of other configuration options use configure help 3 Compile the program by running make make The program should compile without problems and three binaries doxygen and doxyt ag should be available in the bin directory of the distribution 4 Optional Generate the user manual make docs To let doxyg
120. ension HTML HEADER The HTML HEADER tag can be used to specify a user defined HTML header file for each generated HTML page To get valid HTML the header file should contain at least a 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 HTML HEAD 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 title datetime date Sdoxygenversion projectname and 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 If CREATE SUBDIRS is enabled the command relpath can be used to produce a relative path to the root of the HTML output directory e g use relpath doxygen css to refer to the standard style sheet See also section Doxygen usage for information on how to generate the default header that doxygen normally uses HTML FOOTER The HTML FOOTER tag can be used to specify a user defined HTML footer for each generated HTML page To get valid HTML the footer file should cont
121. er the tag name 30 Build related options EXTRACT_ALL If the EXTRACT ALL tag is set to YES doxygen will assume all entities in documenta tion 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 set to YES EXTRACT PRIVATE Ifthe EXTRACT PRIVATE tag is set to YES all private members of a class will be included in the documentation ACT STATIC Ifthe EXTRACT STATIC tag is set to YES all static members of a file will be in cluded in the documentation ACT LOCAL CLASSES Ifthe EXTRACT_LOCAL_CLASSES tag is set to YES classes and structs defined locally in source files will be included in the documentation If set to NO only classes defined in header files are included Does not have any effect for Java sources EXTRACT ANON NSPACES If this flag is set to YES the members of anonymous namespaces will be extracted and appear in the documentation as a namespace called anonymous_namespace file where file will be replaced with the base name of the file that contains the anonymous namespace By default anonymous namespace are hidden EXTRACT LOCAL METHODS Th
122. es the extension that is added to the generated man pages default is the subroutine s section 3 LINKS Ifthe MAN LINKS tag is set to YES 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 source the real man page but without them the man command would be unable to find the correct page The default is NO 39 XML related options GENERATE XML If the GENERATE XML tag is set to YES Doxygen will generate an XML file that cap tures the structure of the code including all documentation XML OUTPUT The XML OUTPUT tag is used to specify where the XML pages will be put If a relative path is entered the value of OUTPUT DIRECTORY will be put in front of it If left blank xm1 will be used as the default path XML SCHEMA The XML SCHEMA tag can be used to specify an XML schema which can be used by a validating XML parser to check the syntax of the XML files XML The XML tag can be used to specify an XML DTD which be used by a validating XML parser to check the syntax of the XML files XML_PROGRAMLISTING Ifthe XML PROGRAMLISTING tag is set to YES Doxygen will dump the pro gram listings including syntax highlighting and cross referencing information to the XML output Note that enabling this will significantly increase the size of the XML output User
123. ew section at the same level will be visible again You can use INTERNAL_DOCS in the config file to show or hide the internal documentation 64 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 TEX User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 90 The title argument is optional and replaces the default title that doxygen normally generates If you do not want any title you can specify not it le as the argument of mainpage Here is an example mainpage My Personal Index Page Nsection intro sec Introduction This is the introduction section install sec Installation subsection stepl Step 1 Opening the box eto You can refer to the main page using ref index if the treeview is disabled otherwise you should use ref main See also section section section subsection and section V page 65 name header This command turns a comment block into a header definition of a member group The comment block should be followed bya G block containing the members of the group See section Member Groups for an example 66 namespace lt name gt Indicates that a comment block contains documentation for a namespace with name lt name gt 67 nosubgrouping This command can be put in the documentation of a class It can be used
124. ewed 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 9 Step 3 Documenting the sources Although documenting the sources is presented as step 3 in a new project this should of course be step 1 Here I assume you already have some code and you want doxygen to generate a nice document describing the API and maybe the internals as well If the EXTRACT ALL option is set to NO in the configuration file the default then doxygen will only generate documentation for documented members files classes and namespaces So how do you document these For members classes and namespaces there are basically two options 1 Place a special documentation block in front of the declaration or definition of the member class or namespace For file class and namespace members it is also allowed to place the documention directly after the member See section Special documentation blocks to learn more about special documentation blocks 2 Place a special documentation block somewhere else another file or another location and put a structural command in the documentation block A structural command links a documentation block to a certain entity that can be documented e g a member class namespace or file See section Do
125. f Opens a file descriptor param pathname The name of the descriptor param flags Opening flags fn int close int brief Closes the file descriptor a fd param fd The descriptor to close N n size t write int fd const char buf size t count brief Writes a count bytes from Na 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 define MAX a b gt a b typedef unsigned int UINT32 int errno int open const char x int int close int size_t write int const char size t int read int char size t Because each comment block in the example above contains a structural command all the comment blocks could be moved to another location or input file the source file for instance without affecting the generated documentation The disadvantage of this approach is that prototypes are duplicated so all changes have to be made twice Because of this you should first consider if this is really needed and avoid structural commands if possible I often receive examples that contain fn command in comment blocks which are place in front of a function This is cle
126. f 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 class Details class Test public Same documentation for both members Details void funclInGroupl void func2InGroupl Function without group Details void ungroupedFunction void funclInGroup2 protected void func2InGroup2 1 void Test funclInGroupl void Test func2InGroupl name Group2 Description of group 2 x Function 2 in group 2 Details x void Test func2InGroup2 Function 1 in group 2 Details void Test funclInGroup2 Q file docs for this file 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 Q Here Group is displayed as a subsection of the Public Members And Group is a separate section because it contains members with different protection levels i e public and protected 17 Subpaging Information can be grouped into pages using the page mainpage commands Normally this results in a flat list of pages where the main page
127. following open source tools e GCC version 3 3 6 Linux and 4 0 1 MacOSX e GNU flex version 2 5 33 Linux and 2 5 4 MacOSX e GNU bison version 1 75 e GNU make version 3 80 e Perl version 5 8 1 e VIM version 6 2 Firefox 1 5 Troll Tech s tmake version 1 3 included in the distribution e teTeX version 2 0 2 CVS 1 12 12 Getting StartedThe executable doxygen is the main program that parses the sources and generates the documentation See section Doxygen usage for more detailed usage information The executable doxytag is only needed if you want to generate references to external documentation i e documentation that was generated by doxygen for which you do not have the sources See section Doxytag usage for more detailed usage information Optionally the executable doxywizard can be used which is a graphical front end for editing the con figuration file that is used by doxygen and for running doxygen in a graphical environment For Mac OS X doxywizard will be started by clicking on the Doxygen application icon The following figure shows the relation between the tools and the flow of information between them it looks complex but that s only because it tries to be complete User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 11
128. frequently asked questions Section Troubleshooting tells you what to do when you have problems The second part forms a reference manual User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS e Section Features presents an overview of what doxygen can do e Section Doxygen History shows what has changed during the development of doxygen and what still has to be done e Section Doxygen usage shows how to use the doxygen program e Section Doxytag usage shows how to use the doxytag program e Section Doxywizard usage shows how to use the doxywizard program e Section Installdox usage shows how to use the installdox script that is generated by doxygen if you use tag files e 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 e Section HTML Commands shows an overview of the HTML commands that can be used within the documentation e Section XML Commands shows an overview of the C style XML commands that can be used within the documentation The third part provides information for developers e Section Doxygen s Internals gives a global overview of how doxygen is internally structured e Section Perl Module output format documentation shows how to use the PerlMod output e Section Internationalization explains how to add support for new o
129. g 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 The tag can be used to show relative paths in the file list If left blank the directory from which doxygen is run is used as the path to strip STRIP FROM INC PATH The STRIP FROM INC PATH tag can be used to strip a user defined part of the path mentioned in the documentation of a class which tells the reader which header file to include in order to use a class If left blank only the name of the header file containing the class definition is used Otherwise one should specify the include paths that are normally passed to the compiler using the I flag CASE_SENSE_NAMES CASE SENSE NAMES tag is set to NO 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 Windows users are advised to set this option to NO 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 JAVADOC_AUTOBRIEF Ifthe JAVADOC_AUTOBRIEF is set to YES then doxygen will interpret the first line until the first dot of a
130. g window Once doxygen finishes the log can be saved as a text file The Wizard Dialog If you select the Wizard button in step 1 then a dialog with a number of tabs will appear The fields in the project tab speak for themselves Once doxygen has finished the Destination directory is where to look for the results Doxygen will put each output format in a separate sub directory The mode tab allows you to select how doxygen will look at your sources The default is to only look for things that have been documented You can also select how doxygen should present the results The latter does not affect the way doxygen parses your source code You can select one or more of the output formats that doxygen should produce For HTML and LaTeX there are additional options Doxygen can produce a number of diagrams Using the diagrams tab you can select which ones to generate For most diagrams the dot tool of the GraphViz package is needed if you use the binary packages for MacOSX this tool is already included Expert dialog The Expert dialog has a number of tab fields 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 58 e For each boolean option those options that are answered with YES or NO
131. gathered and cross referenced doxygen generates output in various formats For this it uses the methods provided by the abstract class OutputGenerator In order to generate output for multiple formats at once the methods of Output List are called instead This class maintains list of concrete output generators where each method called is delegated to all generators in the list To allow small deviations in what is written to the output for each concrete output generator it is pos sible to temporarily disable certain generators The OutputList class contains various disable and enable methods for this The methods OutputList pushGeneratorState and OutputList popGeneratorState used to temporarily save the set of enabled disabled out put generators on a stack The XML is generated directly from the gathered data structures In the future XML will be used as an intermediate language IL The output generators will then use this IL as a starting point to generate the specific output formats The advantage of having an IL is that various independently developed tools written in various languages could extract information from the XML output Possible tools could be e an interactive source browser e aclass diagram generator e computing code metrics Debugging Since doxygen uses a lot of 1ex code it is important to understand how 1ex works for this one should read the man page and to understand what it is doing when
132. graph 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 113 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 114 xrefitem lt key gt heading list title text This command is a generalization of commands such as todo and bug It can be used to create user defined text sections which are automatically cross referenced between the place of occurrence and a re lated page which will be generated On the related page all sections of the same type will be collected The first argument key is a identifier uniquely representing the type of the sect
133. he 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 CREATE SUBDIRS If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub directories in 2 levels under the output directory of each output format and will distribute the generated files over these directories Enabling this option can be useful when feeding doxygen a huge amount of source files where putting all generated files in the same directory would otherwise causes performance problems for the file system 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 Afrikaans Arabic Brazilian Catalan Chinese Croatian Czech Danish Dutch Finnish French Ger
134. he same structure can be made using the defgroup and ingroup commands but for pages the subpage command is often more convenient The main page see mainpage is typically the root of hierarchy This command behaves similar as ref in the sense that it creates a reference to a page labeled lt name gt with the optional link text as specified in the second argument It differs from the ref command in that it only works for pages and creates a parent child relation between pages where the child page or sub page is identified by label lt name gt See the section and subsection commands if you want to add structure without creating multiple pages Note Each page can be the sub page of only one other page and no cyclic relations are allowed i e the page hierarchy must have a tree structure Here is an example mainpage A simple manual Some general info This manual is divided in the following sections subpage intro subpage advanced Advanced usage Npage intro Introduction This page introduces the user to the topic Now you can proceed to the ref advanced advanced section Npage advanced Advanced Usage This page is for advanced users Make sure you have first read ref intro the introduction User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 105 121 section lt section name gt section title Creates a section with name lt section name gt
135. he values of the hash fields are the children of the node e Lists These are references to anonymous Perl lists A list has an undefined number of elements which are the children of the node Each element has the same type string hash or list and the same semantics depending on the location of the list within the tree As you can see the documentation contained in doxydocs does not present any special impediment to be processed by a simple Perl script 182 Data structure describing the Perl Module documentation tree You might be interested in processing the documentation contained in DoxyDocs pm without needing to take into account the semantics of each node of the documentation tree For this purpose Doxygen generates a DoxyModel pm file which contains a data structure describing the type and children of each node in the documentation tree The rest of this section is to be written yet but in the meantime you can look at the Perl scripts generated by Doxygen such as doxylatex pl or doxytemplate latex pl to get an idea on how to use DoxyModel pm Internationalization Support for multiple languages Doxygen has built in support for multiple languages This means that the text fragments generated by doxygen can be produced in languages other than English the default The output language is chosen through the configuration file with default name and known as Doxyfile Currently version 1 5 5 34 languages are supported sort
136. ial commands XML commands and HTML commands that can be used to enhance or structure the documentation inside a comment block If you for some reason have a need to define new commands you can do so by means of an alias definition The definition of an alias should be specified in the configuration file using the ALIASES configuration tag User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 42 25 Simple aliases The simplest form of an alias is a simple substitution of the form name value For example defining the following alias ALIASES sideeffect par Side Effects n will allow you to put the command sideeffect or sideeffect in the documentation which will result in a user defined paragraph with heading Side Effects Note that you can put n s in the value part of an alias to insert newlines Also note that you can redefine existing special commands if you wish Some commands such as xrefitem are designed to be used in combination with aliases 26 Aliases with arguments Aliases can also have one or more arguments In the alias definition you then need to specify the number of arguments between curly braces In the value part of the definition you can place Vx markers where x represents the argument number starting with 1 Here is an example of an alias definition with a single argument ALIASES 1 1 ref 1 Inside a comment block you can use it as follows See Nl
137. ible improvements for future versions e Use one scanner parser per language instead of one big scanner e Move the first pass parsing of documentation blocks to a separate module e Parse defines these are currently gathered by the preprocessor and ignored by the language parser Data organizer This step consists of many smaller steps that build dictionaries of the extracted classes files namespaces variables functions packages pages and groups Besides building dictionaries during this step relations such as inheritance relations between the extracted entities are computed Each step has a function defined in src doxygen cpp which operates on the tree of entries built during language parsing Look at the Gathering information part of parseInput for details The result of this step is a number of dictionaries which can be found in the Doxygen namespace defined in src doxygen h Most elements of these dictionaries are derived from the class De inition The class MemberDef for instance holds all information for a member An instance of such a class can be part of a file class FileDef class class ClassDef a namespace class NamespaceDef a group class GroupDef or a Java package class PackageDef Tag file parser If tag files are specified in the configuration file these are parsed by a SAX based XML parser which can be found in src tagreader cpp The result of parsing a tag file is the insertion
138. ic An example member function More details about this function void example void Test example Nexample 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 class Tag public Test public an overloaded member void example 1 Doxygen will now include links to the external package your own documentation Because the 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 documentation 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 57 doxytag t qt tag QTDIR doc html Doxywizard usageDoxy wizard is a GUI front end for configuring and running doxygen Whe
139. id not need the adapter This way one can say approximately when the language translator class was last updated see details below The newest translator adapter derives from the abstract TranslatorAdapterBase class that derives directly from the abstract Translator class It adds only the private English translator member for easy implementation of the default translation inside the adapter classes and it also enforces implementation of one method for noticing the user that the language translation is not up to date because of that some sentences in the generated files may appear in English Once the oldest adapter class is not used by any of the language translators it can be removed from the doxygen project The maintainers should try to reach the state with the minimal number of translator adapter classes To simplify the maintenance of the language translator classes for the supported languages the translator py Python script was developed located in doxygen doc directory It extracts the important information about obsolete and new methods from the source files for each of the languages The information is stored in the translator report ASCII file translator report txt Looking at the base class of the language translator the script guesses also the status of the translator see the last column of the table with languages above The translator py is called automatically when the doxygen documentation is generated You can als
140. ils doxyrules make This file contains the make rules to build and clean the files that are generated from the Doxyfile Also contains the paths to those files and other relevant information This file is intended to be included by your own Makefile Makefile This is a simple Makefile including doxyrules make To make use of the documentation stored in DoxyDocs pm you can use one of the default Perl Module based generators provided by Doxygen at the moment this includes the Perl Module based LaTeX gen erator see below or write your own customized generator This should not be too hard if you have some knowledge of Perl and it s the main purpose of including the Perl Module backend in Doxygen See below for details on how to do this 180 Using the Perl Module based LaTeX generator The Perl Module based LaTeX generator is pretty experimental and incomplete at the moment but you could find it useful nevertheless It can generate documentation for functions typedefs and variables within User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 180 1 Simple creation of PDF and DVI output using the Perl Module based LaTeX generator 129 files and classes and can be customized quite a lot by redefining TeX macros However there is still no documentation on how to do this Setting the PERLMOD LATEX tag to YES in the Doxyfile enables the creation of some additional files in the perlmod subdirectory of your output dir
141. imply put an exclude pattern like this in the configuration file EXCLUDE PATTERNS x test x 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 7MyClass Doxygen will then remove the and keep the word unlinked My favourite programming language is X Can I still use doxygen No not as such doxygen needs to understand the structure of what it reads If you don t mind spending some time on it there are several options e If the grammar of X is close to C or then it is probably not too hard to tweak src scanner l a bit so the language is supported This is done for all other languages directly supported by doxygen i e Java IDL C PHP e If the grammar of X is somewhat different than you can write an input fil ter that translates X into something similar enough to C C for doxygen to understand this approach is taken for VB Object Pascal and Javascript see http www stack nl dimitri doxygen download htmli helpers e If the grammar is completely different one could write a parser for X and write a backend that produces a similar syntax tree as is done by src scanner and also by src tagreader cpp while reading tag files Help I get the cryptic message input buffer overflow can t enlarge buffer because scanner uses REJECT This error happens when doxygen s lexical scanner has a r
142. in ATEX 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 A white box indicates a class or struct or file 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 the class documentation is currently shown A dark blue arrow indicates an include relation for the include dependency graph or public inher itance for the other graphs A dark green arrow indicates protected inheritance A dark red arrow indicates private inheritance 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 B is a subtype of C e g C could be B Bx lt gt Here are a couple of header file
143. in the configuration file there is a check box e For items taking one of a fixed set of values like OUTPUT LANGUAGE a combo box is used e For items taking an integer value from a range a spinbox is used e For free form string type options there is a one line edit field e 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 lt button to remove the selected string from the list There is also a button that when pressed replaces the selected item in the list with the string entered in the edit field e For file and folder entries there are special buttons that start a file selection dialog The get additional information about the meaning of an option click on the Help button at the bottom right of the dialog and then on the item A tooltip with additional information will appear Menu options The GUI front end has a menu with a couple of useful items Open This is the same as the Load button in the main window and allows to open a configuration file from disk Save as This is the same as the Save button in the main window and can be used to save the current configuration settings to disk Recent configurations Allow to quickly load a recently saved configuration Set as default Stores the current configuration settings as the default to use next time the GUI is started You will be asked to confirm the action Reset Re
144. in the following text This function returns void and not int Equivalent to p To have multiple words in typewriter font use lt tt gt multiple words lt tt gt User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 138 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 139 copydoc lt link object gt Copies a documentation block from the object specified by lt link object gt and pastes it at the location of the command This command can be useful to avoid cases where a documentation block would otherwise have to be duplicated or it can be used to extend the documentation of an inherited member The link object can point to a member of a class file or group a class a namespace a group a page or a file checked in that order Note that if the object pointed to is a member function variable typedef etc the compound class file or group containing it should also be documented for the copying to work To copy the documentation for a member of a class for instance one can put the following in the documen tation copydoc MyClass myfunction documentation if the member is overloaded you should specify the argument types explicitly wi
145. ince there is no such thing as in front of a file Doxygen allows you to put your documentation blocks practically anywhere the exception is inside the body of a function or inside a normal C style comment block User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 21 The price you pay for not putting the documentation block directly before or after an item is the need to put a structural command inside the documentation block which leads to some duplication of information So in practice you should avoid the use of structural commands unless other requirements force you to do so Structural commands like all other commands start with a backslash V or an at sign 8 if you prefer JavaDoc style followed by a command name and one or more parameters For instance if you want to document the class Test in the example above you could have also put the following documentation block somewhere in the input that is read by doxygen Nclass Test brief A test class A more detailed class description Here the special command class is used to indicate that the comment block contains documentation for the class Test Other structural commands are e struct to document a C struct e 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 typedef to document a t
146. ion The second argument is a quoted string representing the heading of the section under which text passed as the forth argument is put The third argument list title is used as the title for the related page containing all items with the same key The keys todo test bug and deprecated are predefined To get an idea on how to use the xrefitem command and what its effect is consider the todo list which for English output can be seen an alias for the command xrefitem todo Todo Todo List User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 103 Since it is very tedious and error prone to repeat the first three parameters of the command for each section the command is meant to be used in combination with the ALIASES option in the configuration file To define a new command reminder for instance one should add the following line to the configuration file ALIASES reminder xrefitem reminders Reminder Reminders Note the use of escaped quotes for the second and third argument of the xrefitem command Commands to create links 115 addindex text This command adds text to the IATEX index 116 anchor lt word gt This command places an invisible named anchor into the documentation to which you can refer with the ref command Note Anchors can currently only be put into a comment block that is marked as a page using page or mainpage mainpage See also sectio
147. is assumed the dot tool can be found on the path DOTFILE_DIRS This tag can be used to specify one or more directories that contain dot files that are included in the documentation see the dotfile command DOT TRANSPARENT Set the DOT TRANSPARENT tag to YES to generate images with a transparent background This is enabled by default which results in a transparent background Warning De pending on the platform used enabling this option may lead to badly anti aliased labels on the edges of a graph i e they become hard to read DOT MULTI TARGETS Setthe DOT MULTI TARGETS tag to YES allow dot to generate multiple output files in one run i e multiple o and T options on the command line This makes dot run faster but since only newer versions of dot 71 8 10 support this this feature is disabled by default GENERATE LEGEND If the GENERATE LEGEND tag is set to YES the default doxygen will generate legend page explaining the meaning of the various boxes and arrows in the dot generated graphs DOT_CLEANUP Ifthe DOT CLEANUP tag is set to YES the default doxygen will remove the intermediate dot files that are used to generate the various graphs 45 Search engine options SEARCHENGINE The SEARCHENGINE tag specifies whether or not the HTML output should con tain a search facility Possible values are YES and NO If set to YES doxygen will
148. is flag is only useful for Objective C code When set to YES local meth ods which are defined in the implementation section but not in the interface are included in the documentation If set to NO the default only methods in the interface are included User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 66 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 HIDE FRIEND COMPOUNDS If the HIDE FRIEND COMPOUNDS tag is set to YES Doxygen will hide all friend class struct union declarations If set to NO the default these declarations will be in cluded in the documentation HIDE IN BODY DOCS Ifthe HIDE IN BODY DOCS tag is set to YES Doxygen will hide any documen tation blocks found inside the body of a function If set to NO the default these blocks will be appended to the function s detailed documentation block
149. ites the character to the output This character has to be escaped in some cases because it is used to prevent auto linking to word that is also a documented class or struct User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 119 178 PHP only commands For PHP files there are a number of additional commands that can be used inside classes to make members public private or protected even though the language itself doesn t support this notion To mark a single item use one of private protected public For starting a section with a certain protec tion level use one of privatesection protectedsection publicsection The latter commands are similar o to private protected and public in C 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 e annotatedclasslist e classhierarchy e define e Munctionindex e header e headerfilelist e inherit eM e postheader HTML commandsHere is a list of all HTML commands that may be used inside the documentation Note that although these HTML tags are translated to the proper commands for outer formats other than HTML all attributes of a HTML tag are passed on to the HTML output only the HREF and NAME attributes for the A tag are the only exception e lt HREF gt Starts a HTML hyper
150. ke sure dot is able to find the font which can be done by putting it in a standard location or by setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory containing the font DOT_FONTPATH By default doxygen will tell dot to use the output directory to look for the FreeSans ttf font which doxygen will put there itself If you specify a different font using DOT_FONTNAME you can set the path where dot can find it using this tag DOT FONTNAME By default doxygen will write a font called FreeSans ttf to the output directory and reference it in all dot files that doxygen generates This font does not include all possible unicode characters however so when you need these or just want a differently looking font you can specify the font name using DOT FONTNAME You need need to make sure dot is able to find the font which can be done by putting it in a standard location or by setting the DOTFONTPATH environment variable by setting DOT FONTPATH to the directory containing the font DOT FONTPATH By default doxygen will tell dot to use the output directory to look for the FreeSans ttf font which doxygen will put there itself If you specify a different font using DOT FONTNAME you can set the path where dot can find it using this tag 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 re
151. l references to the page See also section section section subsection and section ref 71 property qualified property name Indicates that a comment block contains documentation for a property either global or as a member of a class This command is equivalent to var and Mn See also section fn and var 72 protocol lt name gt lt header file gt lt header name gt Indicates that a comment block contains documentation for a protocol in Objective C with name lt name gt The arguments are equal to the class command See also section class 73 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 A String class class String friend int strcmp const String amp const String amp 1 Compares two strings int strcmp const String amp sl const String amp s2 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 93 Nrelates String A string debug function void stringDebug 74 relatesalso lt name gt This command can be used in the
152. lations Setting this tag to YES will force the the CLASS_DIAGRAMS tag to NO 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 GROUP_GRAPHS If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen will gen erate a graph for groups showing the direct groups dependencies UML_LOOK If the UML LOOK tag is set to YES doxygen will generate inheritance and collaboration diagrams in a style similar to the OMG s Unified Modeling Language EMPLATE RELATIONS Ifthe TEMPLATE RELATIONS and HAVE_DOT tags set to YES then doxy gen will show the relations between templates and their instances HIDE_UNDOC_RELATIONS If set to YES the inheritance and collaboration graphs will hide inheritance and usage relations if the target is undocumented or is not a class 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 INC
153. link HTML only e lt A NAME Starts an named anchor HTML only e lt A gt Ends a link or anchor HTML only e lt B gt Starts a piece of text displayed in a bold font e lt B gt Ends a lt B gt section e lt BODY gt Does not generate any output e lt BODY gt Does not generate any output e lt BR gt Forces a line break e lt CENTER gt starts a section of centered text e lt CENTER gt ends a section of centered text e CAPTION Starts a caption Use within a table only User Manual for Doxygen 1 5 6 written by Dimitri van Heesch c 1997 2006 120 e lt CAPTION gt Ends ac e COD is equivalent to V code e lt CODE gt End a CODI aption Use within a table only E gt Starts a piece of text displayed in a typewriter font Note that for C code this command E gt section Note that for C code this command is equivalent to endcode e lt DD gt Starts an item description e DEN Starts a piece of text displayed in a typewriter font e lt DFN gt Ends a lt DFN gt section e lt DIV gt Starts a section with a specific style HTML only e lt DIV gt Ends a section with a specific style HTML only e lt DL gt Starts a description list e lt DL gt Ends a description list e DT Starts an item title e lt e lt DT gt Ends an item title gt Starts a piece of text displayed in a
154. lowing 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 GENERATE is set to YES in the configuration file Generated if GENERATE is set to YES in the configuration file Note that the RTF output probably only looks nice with Microsoft s Word 97 If you have success with other programs please let me know XML Generated if GENERATE XML is set to YES in the configuration file Note that the XML output is still under development The following output formats are indirectly supported by doxygen Compiled HTML Help a k a Windows 98 help Generated by Microsofts HTML Help workshop from the HTML output if GENERATE HTMLHELP is set to YES PostScript Generated from the output by running make ps in the output directory For the best results PDF HYPERLINKS should be set to NO PDF Generated from the output by running make pdf in the output directory To improve the PDF output you typically would want to enable the use of pdf latex by setting USE PDFLATEX to YES in the configuration file In order to get hyperlinks in the PDF file you also need to enable PDF HYPERLINKS Custom CommandsDoxygen provides a large number of spec
155. ly to help editors such as Vim to do proper syntax highlighting by making the number of opening and closing braces the same 159 f Marks the end of a formula that is in a specific environment 160 htmlonly Starts a block of text that will be verbatim included in the generated HTML documentation only The block ends with a endhtmlonly command User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 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 manonly and section Matexonly 161 image lt format gt lt file gt caption lt sizeindication gt lt size gt Inserts an image into the documentation 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 htm1 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 h
156. man Greek Hungarian Italian Japanese Korean Lithuanian Norwegian Persian Polish Por tuguese Romanian Russian Serbian Slovak Slovene Spanish Swedish and Ukrainian USE WINDOWS ENCODING This tag can be used to specify the encoding used in the generated output The encoding is not always determined by the language that is chosen but also whether or not the output is meant for Windows or non Windows users In case there is a difference setting the USE WINDOWS ENCODING tag to YES forces the Windows encoding this is the default for the Windows binary whereas setting the tag to NO uses a Unix style encoding the default for all platforms other than Windows 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 63 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 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 ABBREVIATE BRIEF This tag i
157. mand 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 129 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 130 5 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 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch
158. 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 Another case where you should use doxytag is if you want to create a tag file for the Qt documentation The tool doxytag 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 only use this approach if there is no alternative The doxytag tool may even become obsolete in the future 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 This is eto Nsubsection stepl Step 1 the introduction mainpage My Personal Index Page Nsection intro sec Introduction Nsection install sec 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 unless 1 b Are the members private If so you must set EXTRACT_PRIVAT appear EXTRACT_ALL is set to Y in the documentation ES in the config file to Y ES to make them c Is there a function macro in your clas
159. me paramName gt Refers to a parameter with name paramName Similar to using Va e permission Identifies the security accessibility of a member Ignored by doygen e remarks Identifies the detailed description e returns Marks a piece of text as the return value of a function or method Similar to using return e lt s cref member gt Refers to a member Similar to ref e lt seealso cref member gt Starts a See also section referring to member Similar to using sa member e lt summary gt Identifies the brief description Similar to using brief e term Part of a list command e lt typeparam name paramName Marks a piece of text as the documentation for type pa rameter paramName Similar to using V param e lt typeparamref name paramName gt Refers to a parameter with name paramName Similar to using Va e value Identifies a property Ignored by doxygen Here is an example of a typical piece of code using some of the above commands summary search engine summary class Engine lt summary gt The Search method takes a series of parameters to specify the search criterion User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 124 and returns a dataset containing the result set lt summary gt lt param name connectionString gt the connection string to connect to
160. mplements a quasi intelligent brief description abbreviator that is used to form the text in various listings Each string in this list if found as the leading text of the brief description will be stripped from the text and the result after processing the whole list is used as the annotated text Otherwise the brief description is used as is If left blank the following values are used A name is automatically replaced with the name of the entity The name class The name widget The name file is provides specifies contains represents a an the 39 99 ALWAYS DETAILED SEC If the ALWAYS DETAILED SEC and REPEAT_BRIEF tags both set to YES then doxygen will generate a detailed section even if there is only a brief description INLINE INHERITED MEMB Ifthe INLINE_INHERITED_MEMB tag is set to YES doxygen will show all inherited members of a class in the documentation of that class as if those members were ordinary class members Constructors destructors and assignment operators of the base classes will not be shown 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 ta
161. n provided the implementation of the function or method calls other documented functions The call graph will generated regardless of the value of CALL_GRAPH Note The completeness and correctness of the call graph depends on the doxygen code parser which is not perfect 49 callergraph When this command is put in a comment block of a function or method and HAVE_DOT is set to YES then doxygen will generate a caller graph for that function provided the implementation of the function or method calls other documented functions The caller graph will generated regardless of the value of CALLER_GRAPH Note The completeness and correctness of the caller graph depends on the doxygen code parser which is not perfect User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 85 50 category lt name gt lt header file gt lt header name gt For Objective C only Indicates that a comment block contains documentation for a class category with name lt name gt The arguments are equal to the class command See also section class 51 cass 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 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
162. n Vref 117 endlink This command ends a link that is started with the link command See also section link 118 Wink 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 Mink 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 Mink and Vendlink commands serves as text for a link to the lt link object gt specified as the first argument of Mink See section autolink for more information on automatically generated links and valid link objects User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 104 119 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 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 120 subpage lt name gt text This command can be used to create a hierarchy of pages T
163. n italic font e lt EM gt Ends a lt EM gt section e lt FORM gt Does not generate any output e lt FORM gt Does not generate any output e lt HR gt Writes a horizontal ruler e H1 Starts an unnumbered section e lt H1 gt Ends an unnumberd section e lt H2 gt Starts an unnumbered subsection e lt H2 gt Ends an unnumbered subsection e H3 Starts an unnumbered subsubsection e lt H3 gt Ends an unnumbered subsubsection e I Starts a piece of text displayed in an italic font e lt INPUT gt Does not generate any output e lt I gt Ends a lt I gt section e IMG This command is written with attributes to the HTML output only e lt LI gt Starts a new list item e e lt M e M LI Ends list item e lt ETA gt Does not generate any output ULTICOL gt ignored by doxygen UTLICOL gt ignored by doxygen User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 121 e lt OL gt Starts a numbered item list e lt OL gt Ends a numbered item list e lt P gt Starts a new paragraph e lt P gt Ends a paragraph e lt PRE gt Starts a preformatted fragment e lt PRE gt Ends a preformatted fragment e SMALL Starts a section of text displayed in a smaller font e lt SMALL gt Ends a SMALL section e SPAN Starts an inline text fragment with a specific style HTML only e lt SPAN gt
164. n sty If you need non default options for instance to use pdflatex you need to make a config file with those options set correctly and then specify that config file as the forth argument e For RTF output you can generate the default style sheet file see STYLESHEET FILE using doxygen w rtf rtfstyle cfg Note e 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 docu mentation from an existing configuration file Please use the s option if you send me a configuration file as part of a bug report e To make doxygen read write to standard input output instead of from to a file use for the file name Doxytag usageDoxytag is a small command line based utility It 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 documentation 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
165. n that correspond to a documented class and contain at least one upper case character 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 96 in front of the word User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 20 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 21 Links to functions Links to functions are created if one of the following patterns is encountered 1 functionName cargument list 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 lt argument list gt lt modifiers gt 6 lt className gt lt functionName gt 7 lt className gt lt functionName gt where n gt 0 Note 1 Function arguments should be specified with correct types i e fun const std string amp bool or to match any prototype Note 2 Member function modifiers like const and volatile are required to identify the target i e func int const and fun int target diffe
166. n you start doxywizard it will display the main window the actual look depends on the OS used The windows shows the steps to take to configure and run doxygen The first step is to choose one of the ways to configure doxygen Wizard Click this button to quickly configure the most important settings and leave the rest of the options to their defaults Expert Click this button to to gain access to the full range of configuration options Load Click this button to load an existing configuration file from disk Note that you can select multiple buttons in a row for instance to first configure doxygen using the Wizard and then fine tune the settings via the Expert After doxygen is configured you need to save the configuration as a file to disk This second step allows doxygen to use the configuration and has the additional advantage that the configuration can be reused to run doxygen with the same settings at a later point in time Since some configuration options may use relative paths the next step is to select a directory from which to run doxygen This is typically the root of the source tree and will most of the time already be filled in correctly Once the configuration file is saved and the working directory is set you can run doxygen based on the selected settings Do this by pressing the Start button Once doxygen runs you can cancel it by clicking the same button again The output produced by doxygen is captured and shown in a lo
167. nal package and its documentation are copyright someone else it may be better or even necessary to reference it rather than include a copy of it with your project s doc umentation When the author forbids redistribution this is necessary If the author requires com pliance with some license condition as a precondition of redistribution and you do not want to be bound by those conditions referring to their copy of their documentation is preferable to including a copy User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 44 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
168. ng alias definitions ALIASES Bold 1 lt b gt 1 lt b gt ALIASES Emph 1 lt em gt 1 lt em gt Inside a comment block you can now use This is Bold bold Emph and Emphasized text fragment which will expand to This is a lt b gt bold lt em gt and lt em gt Emphasized lt b gt text fragment Link to external documentationIf 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 depends 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 Copyright issues If the exter
169. nitially it was specifically designed 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 quite similar to the one that is generated by Troll Tech Doxygen understands the C extensions used by Qt such as signals and slots and many of the markup commands used in the Qt sources 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 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 e 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 d
170. not or elseif command See also Vif ifnot elseif Vendif User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 90 elseif lt section label gt Starts a conditional documentation section if the previous section was not enabled 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 section is only enabled if all enclosing sections are enabled as well See also sections endif ifnot else and Velseif 91 endcond Ends a conditional section that was started by cond See also cond 92 endif Ends a conditional section that was started by Vi f or i fnot For each if or Vi fnot one and only one matching Vendi f must follow See also Mif and ifnot 93 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 visual 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
171. ntation feed provides an umbrella under which multiple documentation sets from a single provider such as a company or product suite can be grouped DOCSET BUNDLE ID When GENERATE DOCSET tag is set to YES this tag specifies a string that should uniquely identify the documentation set bundle This should be a reverse domain name style string e g com mycompany MyDocSet Doxygen will append docset to the name HTML DYNAMIC SECTIONS If the HTML DYNAMIC SECTIONS tag is set to YES then the generated HTML documentation will contain sections that can be hidden and shown after the page has loaded For this to work a browser that supports JavaScript and DHTML is required for instance Mozilla 1 07 Firefox Netscape 6 0 Internet explorer 5 0 Konqueror or Safari CHM FILE Ifthe GENERATE HTMLHELP tag is set to YES the CHM FILE tag can be used to specify the file name of the resulting chm file You can add a path in front of the file if the result should not be written to the html output directory HHC LOCATION If the GENERATE HTMLHELP tag is set to YES the HHC LOCATION tag can be used to specify the location absolute path including file name of the HTML help compiler hhc exe If non empty doxygen will try to run the HTML help compiler on the generated index hhp GENERATE CHI Ifthe GENERATE HTMLHELP tag is set to YES the GENE
172. ntation section The section ends with a matching endif command This conditional section is enabled by default To disable it you must put the section label after the ENABLED SECTIONS tag in the configuration file See also sections Vendif Vif Velse and Velseif 96 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 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 99 97 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 98 par parag
173. o provide tooltips at places where an item is referenced There are several ways to mark a comment block as a detailed description 1 You can use the JavaDoc style which consist of a C style comment block starting with two s like this text 2 or you use the Qt style add an exclamation mark after the opening of a C style comment block as shown in this example x text In both cases the intermediate s are optional so x ext is also valid 3 A third alternative is to use a block of at least two C comment lines where each line starts with an additional slash or an exclamation mark Here are examples of the two cases text or Lf text 4 Some people like to make their comment blocks more visible in the documentation For this purpose you can use the following User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 16 OK KR RR RR RR OK RR KR OK OK ckckck ck kk a f ke Ckckock Ck kk kk Kok kk kk ko kk ko ko kk koke kk koe kk kk kk ee ee ee ke note the 2 slashes to end the normal comment block and start a special comment block or 777777777777777777777777777777777777777777777777 ThE nas TEKE lx For the brief description there are also several posibilities 1 One could use the brief command with one of the abo
174. o run the script manualy whenever you feel that it can help you Of course you are not forced to use the results of the script You can find the same information by looking at the adapter class and its base classes How should I update my language translator Firstly you should be the language maintainer or you should let him her know about the changes The following text was written for the language maintainers as User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 135 the primary audience There are several approaches to be taken when updating your language If you are not extremely busy you should always chose the most radical one When the update takes much more time than you expected you can always decide use some suitable translator adapter to finish the changes later and still make your translator working The most radical way of updating the language translator is to make your translator class derive directly from the abstract class Translator and provide translations for the methods that are required to be implemented the compiler will tell you if you forgot to implement some of them If you are in doubt have a look at the TranslatorEnglish class to recognize the purpose of the implemented method Looking at the previously used adapter class may help you sometimes but it can also be misleading because the adapter classes do implement also the obsolete methods see the previous t rFiles example
175. o sa Introduced for compatibility with Javadoc 108 since text 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 109 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 102 110 throw lt exception object gt exception description Synonymous to exception see section exception Note the tag throws is a synonym for this tag 111 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 112 version version number Starts a paragraph where one or more version strings may be entered The paragraph will be indented The text of the para
176. onfig file gt 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 which can be useful for scripting The configuration file has a format that is similar to that of a simple Makefile It consists of a number of assignments tags of the form User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 12 TAGNAME VALUE or VALUE1 VALUE2 You can probably leave the values of most tags in a generated template configuration file to their default value See section Configuration for more details about the configuration file If you do not wish to edit the config file with a text editor you should have a look at doxywizard which is a GUI front end that can create read and write doxygen configuration files and allows setting configuration options by entering them via dialogs For a small project consisting of a few C and or C source and header files you can leave INPUT tag empty and doxygen will search for sources in the current directory If you have a larger project consisting of a source directory or tree you should assign the root directory or directories to the INPUT tag and add one or more file patterns to the FILE PATTERNS tag for instance cpp h Only files that match one of the
177. oxygen can conditionally include documentation blocks e Added Doc like support for member grouping e 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 e 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 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 53 Version 1 0 0 Major new features 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 and 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 and Microsoft IDL Image
178. patterns will be parsed if the patterns are omitted a list of source extensions is used For recursive parsing of a source tree you must set the RECURSIVE tag to YES To further fine tune the list of files that is parsed the EXCLUDE and EXCLUDE PATTERNS tags can be used To omit all cest directories from a source tree for instance one could use EXCLUDE PATTERNS test Doxygen looks at the file s extension to determine how to parse file If a file has an idl or odl extension it is treated as an IDL file If it has a java extension it is treated as a file written in Java Files ending with cs are treated as Cf files and the py extension selects the Python parser Finally files with the extensions php php4 incor phtml are treated as PHP sources Any other extension is parsed as if it is a C C file where files that end with are treated as Objective C source files If you start using doxygen for an existing project thus without any documentation that doxygen is aware of you can still get an idea of what the structure is and how the documented result would look like To do so you must set the EXTRACT ALL tag in the configuration file to YES Then doxygen will pretend everything in your sources is documented Please note that as a consequence warnings about undocumented members will not be generated as long as EXTRACT ALL is set to YES To analyse an existing piece of software it is useful to cross reference
179. php but I have not tried this myself Also read the next section for additional tools you may need to install to run doxygen with certain features enabled 5 Installing the binaries on Windows Doxygen comes as a self installing archive so installation is extremely simple Just follow the dialogs After installation it is recommended to also download and install GraphViz version 2 8 or better is highly recommended Doxygen can use the dot tool of the GraphViz package to render nicer diagrams see the HAVE DOT option in the configuration file If you want to produce compressed HTML files see GENERATE HTMLHELP in the config file then you need the Microsoft HTML help workshop You can download it from Microsoft In order to generate PDF output or use scientific formulas you will also need to install LaTeX and Ghostscript For LaTeX a number of distributions exists Popular onces that should work with doxygen are MikTex and XemTex Ghostscript can be downloaded from Sourceforge After installing LaTeX and Ghostscript you ll need to make sure the tools latex exe pdflatex exe and gswin32c exe are present in the search path of a command box Follow these instructions if you are unsure and run the commands from a command box to verify it works User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 10 6 Tools used to develop doxygen Doxygen was developed and tested under Linux amp MacOSX using the
180. post description of the postcondition 102 pre description of the precondition 103 remarks remark text 104 return description of the return value 105 retval lt return value gt description 106 sa references 107 see references 108 since text 109 test paragraph describing a test case 110 throw lt exception object gt exception description 111 todo paragraph describing what is to be done 112 version version number 97 97 97 97 97 98 98 99 99 99 100 100 100 100 101 101 101 101 101 101 102 102 102 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS 113 warning warning message 114 xrefitem lt key gt heading list title text 115 addindex text 116 anchor lt word gt 117 endlink 118 link lt link object gt 119 ref lt name gt text 120 subpage lt name gt text 121 section lt section name gt section title 122 subsection lt subsection name gt subsection title 123 subsubsection lt subsubsection name gt subsubsection title 124 paragraph lt paragraph name gt paragraph title 125 dontinclude lt file name gt 126 include lt file name gt 127 includelineno lt file name gt 128 line pattern 129 skip pattern 130 skipline pattern 131 until pattern 132 lt file name gt 133 htmlin
181. putting ingroup commands in the documentation for each member you can also group members together by the open marker before the group and the closing marker after the group The markers can be put in the documentation of the group definition or in a separate documentation block Groups themselves 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 Naddtogroup label x to add additional 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 in place to avoid ambiguous linking targets in case a member is not documented in the context of its class namespace or file but only visible as part of a group Doxygen will put members into the group whose definition has the highest priority e g An explicit ingroup overrides an implicit grouping definition via Conflicting grouping definitions with the
182. raph 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 encountered Example Nclass 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 More normal text FF HF FF X F FF F HF class Test 99 param lt parameter name gt 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 checked and a warning is given if the documentation of this or any other parameter is missing or not present in the function declaration or definition The param command has an optional attribute specifying the direction of the attribute Possible values are jn and o
183. rectory to force them to be regenerated 36 LaTeX related options GEN ERATE LA TEX Ifthe GENERATE LATEX tag is set to YES the default doxygen will generate ATEX LAT LAT output EX OUTPUT The LATEX OUTPUT tag is used to specify where the 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 EX_CMD_NAME LATEX CMD NAME tag can be used to specify the LaTeX command name to be invoked If left blank latex will be used as the default command name MAK COMPACT_LAT EINDEX CMD NAME The MAKEINDEX CMD NAME tag can be used to specify the command name to generate index for LaTeX If left blank makeindex will be used as the default command name EX 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 PAP ER TYPE The PAPER TYPE tag can be used to set the paper type that is used by the printer Possible values are e a4 210 x 297 mm e a4wide same as a4 but including the a4wide package e let ter 8 5 x 11 inches e legal 8 5 x 14 inches e executive 7 25 x 10 5 inches User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 200
184. rent member functions Note 3 For JavaDoc compatibility a may be used instead of a in the patterns above Note 4 In the documentation of a class containing a member foo a reference to a global variable is made using foo whereas foo will link to the member For non overloaded members the argument list may be omitted If a function is overloaded and no matching argument list is specified i e pattern 2 or 6 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 7 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 39 22 Links to variables typedefs enum types enum values and de fines 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 7 in this case Example Nfile 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
185. res e Blocks of code are now parsed Function calls and variables are replaced by links to their documen tation if possible e Special example documentation block added This can be used to provide cross references between the documentation and some example code e Documentation blocks can now be placed inside the body of a class e Documentation blocks with line range may now be created using special C line comments e Unrelated members can now be documented A page containing a list of these members is generated e Added an include command to insert blocks of source code into the documentation e Warnings are generated for members that are undocumented e You can now specify your own HTML headers and footers for the generated pages e Option added to generated indices containing all external classes instead of only the used ones Version 0 1 Initial version Doxygen usageDoxygen 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 1 You document your source code with special documentation blocks see section Special documenta tion blocks 2 You generate a configuration file see section Configuration by calling dox
186. rtunately the specification is not very precise and a number of the examples given are of poor quality Here is the list of tags supported by doxygen e lt c gt Identifies inline text that should be rendered as a piece of code Similar to using lt tt gt text lt tt gt User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 123 e lt code gt Set one or more lines of source code or program output Note that this command behaves like code endcode for code but it behaves like the HTML equivalent lt code gt lt code gt for other languages e lt description gt Part of a list command describes an item e lt example gt Marks a block of text as an example ignored by doxygen e exception cref member gt Identifies the exception a method can throw e include Can be used to import a piece of XML from an external file Ignored by doxygen at the moment e lt item gt List item Can only be used inside a lt list gt context e list type type Starts list supported types are bullet or number and table list consists of a number of lt item gt tags A list of type table is a two column table which can a header e lt listheader gt Starts the header of a list of type table e para Identifies a paragraph of text e lt param name paramName Marks a piece of text as the documentation for parameter paramName Similar to using V param e lt paramref na
187. s to YES In this case the Makefile will only contain a target to build refman pdf directly 8 3 RTF output Doxygen combines the RTF output to a single file called refman rtf This file is optimized for importing into the Microsoft Word Certain information is encoded using field To show the actual value you need to select all Edit select all and then toggle fields right click and select the option from the drop down menu 8 4 XML output The XML output consists of a structured dump of the information gathered by doxygen Each compound class namespace file has its own XML file and there is also an index file called index xml A file called combine xslt XSLT script is also generated and can be used to combine all XML files into a single file Doxygen also generates two XML schema files index xsd for the index file and compound xsd for the compound files This schema file describes the possible elements their attributes and how they are struc tured i e it the describes the grammar of the XML files and can be used for validation or to steer XSLT scripts In the addon doxmlparser directory you can find a parser library for reading the XML output produced by doxygen in an incremental way see addon doxmlparser include doxmlintf h for the interface of the library User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 8 5 Man page output 8 5 Man page output The generated man pages can be vi
188. s are tested c cpp java 11 inl h hh hxx hpp idl odl cs php php3 inc m mm FILE VERSION FILTER The FILE VERSION FILTER tag can be used to specify a program or script that doxygen should invoke to get the current version for each file typically from the ver sion control system Doxygen will invoke the program by executing via popen the command command input file where command is the value of the FILE VERSION FILTER tag and input file is the name of an input file provided by doxygen Whatever the program writes to standard output is used as the file version Example of using a shell script as a filter for Unix FILE VERSION FILTER bin sh versionfilter sh Example shell script for CVS bin sh cvs status 1 sed n s Working revision t 0 9 0 9 1 p Example shell script for Subversion bin sh svn stat v 1 sed n s A Z 1 15 r 7s 1 15 r 7s p Example filter for ClearCase FILE VERSION INFO cleartool desc fmt Vn 7 ECURSIVE The RECURSIVE tag 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 I
189. s can be included in the documentation Improved parsing and preprocessing Version 0 4 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 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 Enum types enum values typedefs defines and files can now be documented Completely new documentation that is now generated by Doxygen A lot of small examples are now included Version 0 3 Major new features A PHP based search engine that allows you to search through the generated documentation A configuration file instead of command line options A default configuration file can be generated by doxygen Added an option to generate output for undocumented classes Added an option to generate output for private members User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 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 Version 0 2 Major new featu
190. s email com 1 4 1 Slovak Stanislav Kudl skudlac pobox sk 1 2 18 Slovene Matja Ostroversnik matjaz ostroversnik ostri org 1 4 6 Spanish Bartomeu partomeu loteria3cornella com Up to date Francisco Oltra Thennet foltra puc cl Swedish Mikael Hallin mikaelhallin yahoo se 1 4 6 Ukrainian Olexij Tkatchenko olexij tkatchenko parcs de 1 4 1 Most people on the list have indicated that they were also busy doing other things to speed things up please let them or me know so if you want to help User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 132 If you want to add support for a language that is not yet listed please read the next section Adding a new language to doxygen This short HOWTO explains how to add support for the 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_country_code gt h use xx in the rest of this document 3 Add definition of the symbol for your language into lang cfg h define LANG xx Use capital letters for your xx to be consistent The lang_cfg h defines which language trans lators will be compiled into doxygen executable It is a kind of configuration file If you are sure that you do not need some of
191. s 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 MY MACRO Please read the preprocessing section of the manual for more information 3 When I set EXTRACT ALL to NO none 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 Mile 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 For member functions or functions that are part of a namespace you should document either the class or namespace 4 How can I make doxygen ignore some code fragment User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 46 The new and easiest way is to add one comment block with a cond command at the start and one comment block with a endcond command at the end of the piece of code that should be ignored This should be within the same file of course But you can also use Doxygen s preprocessor for this If you put ifndef DOXYGEN_SHOULD_SKIP_THIS code that must
192. s that together show the various diagrams that doxygen can generate diagrams a h ifndef DIAGRAMS H define DIAGRAMS H class public A m self diagrams_b h ifndef DIAGRAMS B H define DIAGRAMS B H class A class B public A m a dendif diagrams c h ifndef DIAGRAMS define DIAGRAMS include diagrams c h class D class C public public D m d User Manual for Doxygen 1 5 6 written by Dimitri Heesch 1997 2006 34 diagrams_d h ifndef DIAGRAM D H define DIAGRAM D H include diagrams a h include diagrams b h class C 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 PreprocessingSource files that are used as input to doxygen can be parsed by doxygen s built in C preprocessor By default doxygen does only partial preprocessing That is it evaluates conditional compilation statements like fif 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 Then by default doxygen will feed the following to its parser
193. 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 IntegerVariable by putting it into group IntVariables because the second instance of IntegerVariable is undocumented ingroup extern int VarInA Ndefgroup IntVariables Global integer variables x Q an integer variable extern int IntegerVariable 8 Ndefgroup Variables Global variables x 8 a variable in group A x int VarInA int IntegerVariable 8 The ref command can be used to refer to a group The first argument of the ref command should be group s label To use a custom link name you can put the name of the links in double quotes after the label as shown by the following example User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 This is the ref group_label link to this group 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 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
194. se zip or tar the files together into a single file for easier processing Note that when reporting a new bug you ll get a chance to attach a file to it only after submitting the initial bug description You can and are encouraged to add a patch for a bug If you do so please use PATCH as a keyword in the bug entry form If you have ideas how to fix existing bugs and limitations please discuss them on the developers mailing list subscription required Patches can also be sent directly to dimitri stack nl if you prefer not to send them via the bug tracker or mailing list For patches please use diff uN or include the files you modified If you send more than one file please tar or zip everything so I only have to save and download one file Part II Reference Manual Features e 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 C Java Corba and Microsoft Java Python IDL C Objective C and to some extent D and PHP sources e Supports documentation of files namespaces packages classes structs unions templates variables functions typedefs enums and defines User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 51 JavaDoc 1 1 Qt Doc and ECMA 334 C spec compatible Automatically generates class and collaboration diagrams in
195. section fn for an example Note the tag exceptions is a synonym for this tag 94 if lt section label gt Starts a 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 section is only enabled if all enclosing sections are enabled as well Example Unconditionally shown documentation Mif Condl User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 98 Only included if Condl is set endif LE Cond Only included if Cond2 is set if Cond3 Only included if Cond2 and Cond3 are set endif More text endif Unconditional text 0X 00 00 FF FH You can also use conditional commands inside aliases To document a class in two languages you could for instance use Example 2 Nenglish This is English Nendenglish Ndutch Dit is Nederlands Nenddutch class Example 1 Where the following aliases are defined in the configuration file ALIASES english if english endenglish endif dutch if dutch enddutch endif and ENABLED_SECTIONS can be used to enable either english or dutch See also sections endif ifnot else and Velseif 95 ifnot lt section label gt Starts a conditional docume
196. sed directly by doxywizard so it is put in a separate library Each configuration option has one of 5 possible types String List Enum Int or Bool The values of these options are available through the global functions Config_get XXX where XXX is the type of the option The argument of these function is a string naming the option as it appears in the configuration file For instance Con ig get Bool GENERATE TESTLIST returns a reference to a boolean value that is TRUE if the test list was enabled in the config file The function readConfiguration in src doxygen cpp reads the command line options and then calls the configuration parser C Preprocessor The input files mentioned in the config file are by default fed to the C Preprocessor after being piped through a user defined filter if available The way the preprocessor works differs somewhat from a standard C Preprocessor By default it does not do macro expansion although it can be configured to expand all macros Typical usage is to only expand a user specified set of macros This is to allow macro names to appear in the type of function parameters for instance Another difference is that the preprocessor parses but not actually includes code when it encounters a include with the exception of include found inside blocks The reasons behind this deviation from the standard is to prevent feeding multiple definitions of the same functions classes to doxygen s
197. 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 z are omitted 1 is assumed To prevent a macro definition from being undefined via undef or recursively expanded use the operator instead of the operator EXPAND_AS_DEFINED If the MACRO EXPANSION and EXPAND ONLY PREDEF tags are set to YES then this tag can be used to specify a list of macro names that should be expanded The macro User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 77 definition that is found in the sources will be used Use the PREDEFINED tag if you want to use a different macro definition SKIP_FUNCTION_MACROS Ifthe SKIP FUNCTION MACROS tag is set to YES the default then doxy gen s preprocessor will remove all function like macros that are alone on a line have an all uppercase name and do not end with a semicolon Such function macros are typically used for boiler plate code and will confuse the parser if not removed 43 External reference options TAGF ILI ES The TAGFILI ES 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
198. stores the factory defaults as the default settings to use You will be asked to confirm the action Installdox usageInstalldox 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 l tagfile 8 location Each tag file contains information about the files classes and 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 Optionally a list of HTML files may be gi
199. structor def __init__ self self _memVar 0 Documentation for a method param self The object pointer User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 24 def PyMethod self pass A class variable classVar 0 var _memVar member variable Since python looks more like Java than like C or you should set OPTMIZE OUTPUT JAVA to Y1 in the config file 14 Special documentation blocks in VHDL n For VHDL a comment normally start with Doxygen will extract comments starting with There are only two types of comment blocks in VHDL a one line comment representing a brief descrip tion and a multiline comment where the prefix is repeated for each line representing a detailed description Comments are always located in front of the item that is being documented with one exception for ports the comment can also be after the item and is then treated as a brief description for the port Here is an example VHDL file with doxygen comments file brief 2 1 Mux using with select Use standard library library ieee Use logic elements use ieee std logic 1164 11 Mux entity brief description Detailed description of this mux design element entity mux using with is port din 0 in std logic Mux first input din 1 in std logic Mux Second input sel in std logic Select input mux
200. t to support and test the aligned representation GENERATE 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 index hhp is a project file that can beread by Microsoft s HTML Help Workshop on Windows The HTML Help Workshop contains a compiler that can convert all HTML output generated by doxygen into a single compiled HTML file chm Compiled HTML files are now used as the Win dows 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 The HTML workshop also contains a viewer for compressed HTML files GENERATE DOCSET If the GENERATE DOCSET tag is set to YES additional index files will be generated that can be used as input for Apple s Xcode 3 integrated development environment introduced with OSX 10 5 Leopard To create a documentation set doxy gen will generate a Makefile in the HTML output directory Running make will pro duce the docset in that directory and running make install will install the docset in Library Developer Shared Documentation DocSets so that Xcode will find it at startup DOCSET_FEEDNAME When GENERATE DOCSET tag is set to YES this tag determines the name of the feed A docume
201. ted for each function For a part this is because the code parser isn t smart enough at the moment try to improve this in the future But even with these improvements not everything 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 or relatesalso 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 e Version 1 8 6 of dot and maybe earlier versions too do not generate proper map files causing the graphs that doxygen generates not to be properly clickable e PHP only Doxygen requires that all PHP statements i e code is wrapped in a functions methods otherwise you may run into parse problems 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 50 How to report a bug Bugs are tracked in GNOME s bugzilla database Before submitting
202. that comes with doxygen is build with this patch applied Sun compiler problems It appears that doxygen doesn t work properly if it is compiled with Sun s C WorkShop 6 Compiler I cannot verify this myself as I do not have access to a Solaris machine with this compiler With GNU compiler it does work and installing Sun patch 111679 13 has also been reported as a way to fix the problem when configuring with static I got User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 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 LINK LFLAGS o TARGET OBJECTS OBJMOC LIBS Bdynamic GCC compiler problems Older versions of the GNU compiler have problems with constant strings containing characters with 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 On some platforms such as OpenBSD using some versions of gcc with O2 can lead to eating all memory during the compilation of files such as config cpp As a workaround use debug as a configure option or omit th
203. the database holding the content to search lt param gt lt param name maxRows gt The maximum number of rows to return in the result set lt param gt lt param name searchString gt The text that we are searching for lt param gt lt returns gt A DataSet instance containing the matching rows It contains a maximum number of rows specified by the maxRows parameter lt returns gt public DataSet Search string connectionString int maxRows int searchString DataSet ds new DataSet return ds Part III Developers Manual Doxygen s internals Doxygen s internals Note that this section is still under construction The following picture shows how source files are processed by doxygen input files config file Config parser XML get settings HTML LaTeX C Preprocessor Language parser Data organiser input string RTF drives tag file parser drives Source Parser drives Figure 2 Data flow overview User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 125 The following sections explain the steps above in more detail Config parser The configuration file that controls the settings of a project is parsed and the settings are stored in the singleton class Configin src config h The parser itself is written using flex and can be found in src config 1 This parser is also u
204. 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 109 135 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 Narg Nc AlignLeft left alignment Narg Nc AlignCenter center alignment Narg Nc 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 136 b lt word gt Displays the argument lt word gt using a bold font Equivalent to lt b gt word lt b gt To put multiple words in bold use lt b gt multiple words lt b gt 137 c lt word gt Displays the argument lt word gt using a typewriter font Use this to refer to a word of code Equivalent to tt word tt7 Example Typing This function returns void and not Nc int will result
205. the languages you can remove comment out definitions of symbols for the languages or you can say undef instead of define for them 4 Edit language cpp Add a ifdef LANG xx include lt translator_xx h gt fendif Remember to use the same symbol LANG_xx that you added to lang_cfg h I e the xx should be capital letters that identify your language On the other hand the xx inside your translator xx h should use lower case Now in setTranslator add ifdef LANG xx else if L EQUAL your language name theTranslator new TranslatorYourLanguage endif after the if Le it must be placed after the code for creating the English translator at the beginning and before the else part that creates the translator for the default language English again 5 Edit libdoxygen pro in and add translator xx htothe HEADERS line 6 Edit translator xx h e Rename TRANSLATOR EN H to TRANSLATOR XX H twice ie in the ifndef and fdefine preprocessor commands at the beginning of the file e Rename TranslatorEnglish to TranslatorYourLanguage e In the member idLanguage change english into the name of your language use lower case characters only Depending on the language you may also wish to change the member functions latexLanguageSupportCommand idLanguageCharset and others you will recog nize them when you start the work User Manual for Doxygen 1
206. thout spaces like in the following copydoc MyClass myfunction typel type2 Qualified names are only needed if the context in which the documentation block is found requires them The copydoc command can be used recursively but cycles in the copydoc relation will be broken and flagged as an error Note that both the brief description and the detailed documentation will be copied See cmdcopybrief and cmdcopydetails for copying only the brief or detailed part of the comment block 140 copybrief lt link object gt Works in a similar way as copydoc but will only copy the brief description not the detailed documentation 141 copydetails lt link object gt Works in a similar way as copydoc but will only copy the detailed documentation not the brief description 142 dot Starts a text fragment which should contain a valid description of a dot graph The text fragment ends with enddot Doxygen will pass the text on to dot and include the resulting image and image map into the User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 111 output The nodes of a graph can be made clickable by using the URL attribute By using the command ref inside the URL value you can conveniently link to an item inside doxygen Here is an example class B class B class C class C trs Nmainpage Class relations expressed via an inline dot graph dot digraph example nod
207. tical The following text describes the usage of translator adapters to solve the problem The role of Translator Adapters Whenever the Translator class interface changes in the new release the new class TranslatorAdapter x y z is added to the translator adapter h file here x y and z are numbers that correspond to the current official version of doxygen All translators that previously derived from the Translator class now derive from this adapter class The TranslatorAdapter x y z class implements the new required methods If the new method replaces some similar but obsolete method s e g if the number of arguments changed and or the func tionality of the older method was changed or enriched the Transl1atorAdapter x y z class may use the obsolete method to get the result which is as close as possible to the older result in the target language If it is not possible the result the default translation is obtained using the English translator which is by definition always up to date For example when the new trFile method with parameters to determine the capitalization of the first letter and the singular plural form was introduced to replace the older method trFiles without arguments the following code appeared in one of the translator adapter classes This is the default implementation of the obsolete method used in the documentation of a group before the list of links to documented files This is possibly localized
208. tions between the files in the directories DOT GRAPH MAX NODES The DOT GRAPH MAX NODES tag can be used to set the maximum number of nodes that will be shown in the graph If the number of nodes in a graph becomes larger than this value doxygen will truncate the graph which is visualized by representing a node as a red box Note that doxygen if the number of direct children of the root node in a graph is already larger than DOT GRAPH MAX NODES then the graph will not be shown at all Also note that the size of a graph can be further restricted by MAX DOT GRAPH DEPTH MAX DOT GRAPH DEPTH MAX DOT GRAPH DEPTH tag can be used to set the maximum depth of the graphs generated by dot A depth value of 3 means that only nodes reachable from the root by following a path via at most 3 edges will be shown Nodes that lay further from the root node will be omitted Note that setting this option to 1 or 2 may greatly reduce the computation time needed for large code bases Also note that the size of a graph can be further restricted by DOT GRAPH MAX _ NODES Using a depth of 0 means no depth restriction the default DOT IMAGE FORMAT The DOT IMAGE FORMAT tag can be used to set the image format of the images generated by dot Possible values are gif jpg and png If left blank png will be used DOT PATH This tag can be used to specify the path where the dot tool can be found If left blank it
209. 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 Note that the last two arguments can also specified using the headerfile command Example A dummy class x class Test hi class Test class h inc class h brief This is a test class Some details about the Test class 52 def lt name gt Indicates that a comment block contains documentation for a define macro Example Nfile define h brief testing defines This is to test the documentation of defines def Computes the maximum of x a y x Computes the absolute value of its argument x x define ABS x gt 0 x define x y x y define MIN x y x y y x lt Computes the minimum of Na x and y User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 86 53 defgroup lt name gt group title Indicates that a comment block contains documentation for a group of classes files or namespaces This can be use
210. to YES class diagram in HTML for classes with base or super classes Setting the tag to NO turns the diagrams off Note that this option is superseded by the HAVE_DOT option below This is only a fallback It is recommended to install and use dot since it yields more powerful graphs MSCGEN PATH You can define message sequence charts within doxygen comments using the msc com the default doxygen will generate a mand Doxygen will then run tool to produce the chart and insert it in the documen tation The MSCGI EN_PATH tag allows you to specify the directory where the mscgen tool resides If left empty the tool is assumed to be found in the default search path User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 78 HAVE DOT Ifyou set the HAVE_DOT tag to YES 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 DOT FONTNAME By default doxygen will write a font called FreeSans tt f to the output directory and reference it in all dot files that doxygen generates This font does not include all possible unicode characters however so when you need these or just want a differently looking font you can specify the font name using DOT_FONTNAME You need need to ma
211. tor adapter class For example your translator class have to use TranslatorAdapter_1_2_4 if it does not implement the methods below the comment new since 1 2 4 When you implement them your class should use newer translator adapter Run the translator py script occasionaly and give it your xx identification from t ranslator xx h to create the translator report shorter also produced faster it will contain only the information related to your translator Once you reach the state when the base class should be changed to some newer adapter you will see the note in the translator report Warning Don t forget to compile Doxygen to discover whether it is compilable The translator py does not check if everything is correct with respect to the compiler Because of that it may lie sometimes about the necessary base class The most obsolete language translators would lead to implementation of too complicated adapters Be cause of that doxygen developers may decide to derive such translators from the TranslatorEnglish class which is by definition always up to date When doing so all the missing methods will be replaced by the English translation This means that not implemented methods will always return the English result Such translators are marked using word obsolete You should read it really obsolete No guess about the last update can be done Often it is possible to construct better result from the obsolete methods Beca
212. ule that matches more than 256K of input characters in one go I ve seen this happening on a very large generated file gt 256K lines where User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 48 the built in preprocessor converted it into an empty file with gt 256K of newlines Another case where this might happen is if you have lines in your code with more than 256K characters If you have run into such a case and want me to fix it you should send me a code fragment that triggers the message To work around the problem put some line breaks into your file split it up into smaller parts or exclude it from the input using EXCLUDE 14 When running make in the latex dir I get TeX capacity exceeded Now what You can edit the texmf cfg file to increase the default values of the various buffers and then run texconfig init 15 Why are dependencies via STL classes not shown in the dot graphs Doxygen is unware of STL classes unless the option BUILTIN STL SUPPORT is turned on 16 I have problems getting the search engine to work with 5 and or windows Please read this for hints on where to look 17 CanI configure doxygen from the command line Not via command line options but doxygen can read from st din so you can pipe things through it Here s an example how to override an option in a configuration file from the command line assuming a unix environment cat Doxyfile echo PROJE
213. up groupl More documentation for the first group et another function in group 1 x void func2 yet another function in group 1 void func3 8 end of groupl 16 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 Jre block or a x block if you prefer 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 5 6 written by Dimitri van Heesch 1997 2006 30 level group the group is displayed as a subsection o
214. ur project consists of Java or Python sources only Doxygen will then generate output that is more tailored for that lan guage For instance namespaces will be presented as packages qualified scopes will look different etc OPTIMIZE FOR FORTRAN Set the OPTIMIZE FOR FORTRAN tag to YES if your project consists of Fortran sources Doxygen will then generate output that is tailored for Fortran OPTIMIZE OUTPUT VHDL Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL sources Doxygen will then generate output that is tailored for VHDL SUBGROUPING Set the SUBGROUPING tag to YES the default to allow class member groups of the same type for instance a group of public functions to be put as a subgroup of that type e g under the Public Functions section Set it to NO to prevent subgrouping Alternatively this can be done per class using the nosubgrouping command TYPEDEF_HIDES_STRUCT When TYPEDEF_HIDES_STRUCT is enabled a typedef of a struct union or enum is documented as struct union or enum with the name of the typedef So typedef struct TypeS TypeT will appear in the documentation as a struct with name TypeT When disabled the typedef will appear as a member of a file namespace or class And the struct will be named Types This can typically be useful for C code in case the coding convention dictates that all compound types are typedef ed and only the typedef is referenced nev
215. use of that the translator adapter classes should be used if possible On the other hand implementation of adapters for really obsolete translators brings too much maintenance and run time overhead User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 Index 118 118 amp 118 lt 118 gt 118 117 118 a 108 addindex 103 addtogroup 84 94 anchor 103 arg 109 attention 94 author 94 b 109 brief 95 bug 95 c 109 callergraph 84 callgraph 84 category 85 class 85 code 110 cond 95 copydoc 110 date 96 def 85 defgroup 86 deprecated 96 details 96 dir 86 dontinclude 106 dot 110 dotfile 112 e 112 else 96 elseif 97 em 112 endcode 113 endcond 97 enddot 113 endhtmlonly 113 endif 97 endlatexonly 113 endlink 103 endmanonly 113 endmsc 113 endverbatim 113 endxmlonly 114 enum 86 example 87 exception 97 MS 114 MI 114 M 114 Mile 87 fn 88 headerfile 88 hideinitializer 89 htmlinclude 108 htmlonly 114 Vif 97 ifnot 98 image 115 include 106 includelineno 107 ingroup 89 interface 89 internal 89 invariant 98 latexonly 115 Vi 116 line 107 link 103 mainpage 89 manonly 116 Wnsc 111 n 116 namespace 90 nosubgrouping 90 note 99 overload 90 p 117 package 91 page 91 par 99 paragraph 105 param
216. ust 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 75 note WordPad write and others do not support links RTF_STYLESHEET_FILE Load stylesheet definitions from file Syntax is similar to doxygen s config file i e a series of assignments You only have to provide replacements missing definitions are set to their default value See also section Doxygen usage for information on how to generate the default style sheet that doxygen normally uses RTF_EXTENSIONS_FILE Set optional variables used in the generation of an RTF document Syntax is similar to doxygen s config file A template extensions file can be generated using doxygen e rtf extensionFile 38 Man page related options GENERATE If the GENERATE MAN tag is set to YES the default doxygen will generate man pages for classes and files MAN OUTPUT The MAN OUTPUT tag is used to specify where the man pages will be put If a relative path is entered the value of OUTPUT_DIRECTORY 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 MAN EXTENSION The MAN EXTENSION tag determin
217. ut Here is an example for the function memcpy Copies bytes from a source memory area to a destination memory area where both areas may not overlap param out dest The memory area to copy to User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 100 param in src The memory area to copy from param in n The number of bytes to copy void memcpy void dest const void src size t n If a parameter is both input and output use in out as an attribute The parameter description is a paragraph with no special internal structure All visual enhancement com mands 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 V param description ends when a blank line or some other sectioning command is encountered See section fn for an example 100 tparam lt template parameter name gt description Starts a template parameters for a class or function template parameter with name template parameter name gt followed by a description of the template parameter Otherwise similar to cmdparam 101 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 Multipl
218. ut See section HTML Commands for an overview of all supported HTML tags Documenting the code User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 15 10 Special documentation blocks A special documentation block is a C or C style comment block with some additional markings so doxygen knows it is a piece of documentation that needs to end up in the generated documentation For Python and VHDL code there are a different comment conventions which can be found in section Special documentation blocks in Python and Special documentation blocks in VHDL respectively For each code item there are two or in some cases three types of descriptions which together form the documentation a brief description and detailed description both are optional For methods and func tions there is also a third type of description the so called in body description which consists of the concatenation of all comment blocks found within the body of the method or function Having more than one brief or detailed description is allowed but not recommended as the order in which the descriptions will appear is not specified As the name suggest a brief description is a short one liner whereas the detailed description provides longer more detailed documentation An in body description can also act as a detailed description or can describe a collection of implementation details For the HTML output brief descriptions are also use t
219. utput languages Doxygen license Copyright 1997 2008 by Dimitri van Heesch Permission to use copy modify and distribute this software and its documentation under the terms of the GNU General Public License is hereby granted No representations are made about the suitability of this software for any purpose It is provided as is without express or implied warranty See the GNU General Public License for more details Documents produced by doxygen are derivative works derived from the input used in their production they are not affected by this license User examples Doxygen supports a number of output formats where HTML is the most popular one I ve gathered some nice examples see http www doxygen org results html of real life projects using doxy gen These are of larger list of projects that use doxygen see http www doxygen org projects html If you know other projects let me know and add them User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 CONTENTS Future work Although doxygen is used successfully by a lot of people already there is always room for improvement Therefore I have compiled a todo wish list see http www doxygen org todo htm1 of possi ble 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
220. van Heesch dimitri stack nl up to date English Dimitri van Heesch dimitri stack nl up to date Finnish Antti Laine antti a laine tut 1 up to date French Xavier Outhier xouthier yahoo fr 1 5 4 German Jens Seidel jensseidel users sf net up to date Greek Paul Gessos nickreserved yahoo com 1 5 4 Hungarian Akos Kiss akiss users sourceforge net 1 4 6 F ldv ri Gy rgy foldvari lost cyberspace Indonesian Hendy Irawan ceefour gauldong net 1 4 6 Italian Alessandro Falappa alessandro falappa net up to date Ahmed Aldo Faisal aaf236cam ac uk Japanese Ryunosuke Satoh sun594 hotmail com 1 5 4 Kenji Nagamatsu naga joyful club ne jp Iwasa Kazmi iwasa cosmo system jp JapaneseEn see the Japanese language English based Korean Kim Taedong lylo040gmail com up to date SooYoung Jung jung50006gnail com Richard Kim ryk dspwiz com KoreanEn see the Korean language English based Lithuanian Tomas Simonaitis haden homelan 1t 1 4 6 Mindaugas Radzius mindaugastadzius takas 1t Aidas Berukstis aidasber takas 1t Macedonian Slave Jovanovski slave jovanovski yahoo com 1 5 04 Norwegian Lars Erik Jordet Le jordet gmail com 1 4 6 Persian Ali Nadalizadeh nadalizadeh gmail com up to date Polish Piotr Kaminski Piotr KaminskiGctm gdynia pi 1 4 6 Grzegorz Kowal g kowal poczta onet pl Portuguese Rui Godinho Lopes ruiglopes yahoo com 1 3 3 Romanian Alexandru Iosup aiosup yahoo com 1 4 1 Russian Alexandr Chelpanov cav cryptopro ru up to date Serbian Dejan Milosavljevic dmilo
221. ve comment blocks This command ends at the end of a paragraph so the detailed description follows after an empty line Here is an example brief Brief description Brief description continued Detailed description starts here 2 IFJAVADOC AUTOBRIEF is set to YES in the configuration file then using JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line Here is an example Brief description which ends at this dot Details follow here The option has the same effect for multi line special C comments Brief description which ends at this dot Details follow here 3 A third option is to use a special C style comment which does not span more than one line Here are two examples Brief description Detailed description or Brief descripion Detailed description starts here Note the blank line in the last example which is required to separate the brief description from the block containing the detailed description The JAVADOC_AUTOBRIEF should also be set to NO for this case As you can see doxygen is quite flexible The following however is not legal User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 17 Brief description which is really a detailed description since it spans multiple lines Oops another detailed description
222. ven 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 Configuration 28 Format A configuration file is a free form ASCII text file with a structure that is similar to that of a Makefile with the default name Doxy file It is parsed by doxygen The file may contain tabs and newlines for formatting purposes 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 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 of non blanks If the value should contain one or more blanks it must be surrounded by quotes Multiple lines can be concatenated by inserting a backslash as the last character of a line Environment variables can be expan
223. verloaded member function Details An enum type More details enum EType Vall lt enum value 1 Val2 lt enum value 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 x GVal2 global enum value 2 x A macro definition define ABS x gt 0 typedef Test B fn typedef Test B A type definition 23 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 Nfile restypedef cpp An example of resolving typedefs Nstruct CoordStruct A coordinate pair struct CoordStruct The x coordinate x User Manual for Doxygen 1 5 6 written by Dimitri van Heesch c 1997 2006 41 float x The y coordinate float y Creates a type name for CoordStruct typedef CoordStruct Coord This function returns the addition of cl 2 i e 1 2 1 2 1 c2 Output Formats 24 Output Formats The fol
224. wer USE_PDFLATEX If the LATEX PDFLATEX tag is set to YES doxygen will use pdflatex to generate the PDF file directly from the IATEX files LATEX BATCHMODE If the LATEX BATCHMODE tag is set to YES doxygen will add the batchmode command to the generated files This will instruct ATEX to keep running if errors occur instead of asking the user for help This option is also used when generating formulas in HTML LATEX HIDE INDICES If LATEX HIDE INDICES is set to YES then doxygen will not include the index chapters such as File Index Compound Index etc in the output 37 RIF related options GENERATE If the GENERATE tag is set to YES doxygen will generate RTF output The RTF output is optimized for Word 97 and may not look too pretty with other readers editors RTF OUTPUT The 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 Ifthe COMPACT_RTF tag is set to YES doxygen generates more compact RTF documents This may be useful for small projects and may help to save some trees in general RTF_HYPERLINKS If the RTF_HYPERLINKS tag is set to YES the RTF that is generated will con tain hyperlink fields The RTF file will contain links G
225. ygen with g option doxygen g config file 3 You edit the configuration file so it matches your project In the configuration file you can specify the input files and a lot of optional information 4 You let doxygen generate the documentation based on the settings in the configuration file doxygen config file 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 User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 55 doxygen u config file 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 e 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 e For LaTeX output you can generate the first part of re fman tex see LATEX HEADER and the style sheet included by that header normally doxygen st y using doxygen w latex header tex doxyge
226. yle sheets CSS should be used I m using Mozilla Safari Konqueror and sometimes IE6 to test the generated output Some of the features the HTML section such as GENERATE TREEVIEW require a browser that supports DHTML and Javascript If you plan to use the search engine see SEARCHENGINE you should view the HTML output via a PHP enabled web server e g apache with the PHP module installed 8 2 LaTeX output The generated IATEX documentation must first be compiled by a ATEX compiler I use a recent teTeX distri bution To simplify the process of compiling the generated documentation doxygen writes a Makefile into the Latex directory The contents and targets in the Makefile depend on the setting of USE PDFLATEX If it is disabled set to NO then typing make in the latex directory a dvi file called refman dvi will be generated This file can then be viewed using xdvi or converted into a PostScript file refman ps by typing make ps this requires dvips To put 2 pages on one physical page use make ps_2on1 instead The resulting PostScript file can be send to a PostScript printer If you do not have a PostScript printer you can try to use ghostscript to convert PostScript into something your printer understands Conversion to PDF is also possible if you have installed the ghostscript interpreter just type make pdf or make pdf 2011 To get the best results for PDF output you should set the PDF HYPERLINKS and USE PDFLATEX tag
227. ype definition e file to document a file e namespace to document a namespace package to document a Java package interface to document an IDL interface See section Special Commands for detailed information about these and many other commands To document a member of a C class you must also document the class itself The same holds for namespaces To document a global C function typedef enum or preprocessor definition you must first document the file that contains it usually this will be a header file because that file contains the information that is exported to other source files Let s repeat that because it is often overlooked to document global objects functions typedefs enum macros etc you must document the file in which they are defined In other words there must at least be a file ora file x line in this file Here is an example of a C header named st ructcmd h that is documented using structural commands User Manual for Doxygen 1 5 6 written by Dimitri van Heesch 1997 2006 file structcmd h brief A Documented file Details def a b brief A macro that returns the maximum of a a and a b Details var typedef unsigned int UINT32 brief A type definition for a Details Nvar int errno brief Contains the last error code Warning Not thread safe fn int open const char pathname int flags Morie

Manual for version 1.5.6 Written by Dimitri van Heesch c 1997-2007

Contents

Download Pdf Manuals

Related Search

Related Contents