diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/commands.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/commands.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,2526 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 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. + * + */ +/*! \page commands Special Commands + +\section cmd_intro Introduction + +All commands in the documentation start with a backslash (\\) or an +at-sign (\@). If you prefer you can replace all commands starting with a +backslash below by their counterparts that start with an at-sign. + +Some commands have one or more arguments. +Each argument has a certain range: + +If [square] brackets are used the argument is optional. + +Here is an alphabetically sorted list of all commands with references to their +documentation: +\secreflist +\refitem cmda \\a +\refitem cmdaddindex \\addindex +\refitem cmdaddtogroup \\addtogroup +\refitem cmdanchor \\anchor +\refitem cmdarg \\arg +\refitem cmdattention \\attention +\refitem cmdauthor \\author +\refitem cmdb \\b +\refitem cmdbrief \\brief +\refitem cmdbug \\bug +\refitem cmdc \\c +\refitem cmdcallgraph \\callgraph +\refitem cmdcallergraph \\callergraph +\refitem cmdcategory \\category +\refitem cmdclass \\class +\refitem cmdcode \\code +\refitem cmdcond \\cond +\refitem cmdcopybrief \\copybrief +\refitem cmdcopydetails \\copydetails +\refitem cmdcopydoc \\copydoc +\refitem cmddate \\date +\refitem cmddef \\def +\refitem cmddefgroup \\defgroup +\refitem cmddeprecated \\deprecated +\refitem cmddetails \\details +\refitem cmddir \\dir +\refitem cmddontinclude \\dontinclude +\refitem cmddot \\dot +\refitem cmddotfile \\dotfile +\refitem cmde \\e +\refitem cmdelse \\else +\refitem cmdelseif \\elseif +\refitem cmdem \\em +\refitem cmdendcode \\endcode +\refitem cmdendcond \\endcond +\refitem cmdenddot \\enddot +\refitem cmdendhtmlonly \\endhtmlonly +\refitem cmdendif \\endif +\refitem cmdendlatexonly \\endlatexonly +\refitem cmdendlink \\endlink +\refitem cmdendmanonly \\endmanonly +\refitem cmdendmsc \\endmsc +\refitem cmdendverbatim \\endverbatim +\refitem cmdendxmlonly \\endxmlonly +\refitem cmdenum \\enum +\refitem cmdexample \\example +\refitem cmdexception \\exception +\refitem cmdextends \\extends +\refitem cmdfdollar \\f\$ +\refitem cmdfbropen \\f[ +\refitem cmdfbrclose \\f] +\refitem cmdfcurlyopen \\f{ +\refitem cmdfcurlyclose \\f} +\refitem cmdfile \\file +\refitem cmdfn \\fn +\refitem cmdheaderfile \\headerfile +\refitem cmdhideinitializer \\hideinitializer +\refitem cmdhtmlinclude \\htmlinclude +\refitem cmdhtmlonly \\htmlonly +\refitem cmdif \\if +\refitem cmdifnot \\ifnot +\refitem cmdimage \\image +\refitem cmdimplements \\implements +\refitem cmdinclude \\include +\refitem cmdincludelineno \\includelineno +\refitem cmdingroup \\ingroup +\refitem cmdinternal \\internal +\refitem cmdinvariant \\invariant +\refitem cmdinterface \\interface +\refitem cmdlatexonly \\latexonly +\refitem cmdli \\li +\refitem cmdline \\line +\refitem cmdlink \\link +\refitem cmdmainpage \\mainpage +\refitem cmdmanonly \\manonly +\refitem cmdmemberof \\memberof +\refitem cmdmsc \\msc +\refitem cmdn \\n +\refitem cmdname \\name +\refitem cmdnamespace \\namespace +\refitem cmdnosubgrouping \\nosubgrouping +\refitem cmdnote \\note +\refitem cmdoverload \\overload +\refitem cmdp \\p +\refitem cmdpackage \\package +\refitem cmdpage \\page +\refitem cmdpar \\par +\refitem cmdparagraph \\paragraph +\refitem cmdparam \\param +\refitem cmdpost \\post +\refitem cmdpre \\pre +\refitem cmdprivate \\private +\refitem cmdprivate \\privatesection +\refitem cmdproperty \\property +\refitem cmdprotected \\protected +\refitem cmdprotected \\protectedsection +\refitem cmdprotocol \\protocol +\refitem cmdpublic \\public +\refitem cmdpublic \\publicsection +\refitem cmdref \\ref +\refitem cmdrelates \\relates +\refitem cmdrelatesalso \\relatesalso +\refitem cmdremarks \\remarks +\refitem cmdreturn \\return +\refitem cmdretval \\retval +\refitem cmdsa \\sa +\refitem cmdsection \\section +\refitem cmdsee \\see +\refitem cmdshowinitializer \\showinitializer +\refitem cmdsince \\since +\refitem cmdskip \\skip +\refitem cmdskipline \\skipline +\refitem cmdstruct \\struct +\refitem cmdsubpage \\subpage +\refitem cmdsubsection \\subsection +\refitem cmdsubsubsection \\subsubsection +\refitem cmdtest \\test +\refitem cmdthrow \\throw +\refitem cmdtodo \\todo +\refitem cmdtparam \\tparam +\refitem cmdtypedef \\typedef +\refitem cmdunion \\union +\refitem cmduntil \\until +\refitem cmdvar \\var +\refitem cmdverbatim \\verbatim +\refitem cmdverbinclude \\verbinclude +\refitem cmdversion \\version +\refitem cmdwarning \\warning +\refitem cmdweakgroup \\weakgroup +\refitem cmdxmlonly \\xmlonly +\refitem cmdxrefitem \\xrefitem +\refitem cmddollar \\\$ +\refitem cmdat \\\@ +\refitem cmdbackslash \\\\ +\refitem cmdamp \\\& +\refitem cmdtilde \\~ +\refitem cmdlt \\\< +\refitem cmdgt \\\> +\refitem cmdhash \\\# +\refitem cmdperc \\\% +\refitem cmdquot \\\" +\endsecreflist + +The following subsections provide a list of all commands that are recognized by +doxygen. Unrecognized commands are treated as normal text. + + +\htmlonly
\endhtmlonly +

+\htmlonly --- \endhtmlonly +Structural indicators +\htmlonly --- \endhtmlonly +

+\htmlonly
\endhtmlonly + +\section cmdaddtogroup \\addtogroup [(title)] + \addindex \\addtogroup + Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to + that command using the same \ 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: + +\verbatim + /*! \addtogroup mygrp + * Additional documentation for group `mygrp' + * @{ + */ + + /*! + * A function + */ + void func1() + { + } + + /*! Another function */ + void func2() + { + } + + /*! @} */ +\endverbatim + + \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup" and + \ref cmdweakgroup "\\weakgroup". + +
+\section cmdcallgraph \\callgraph + + \addindex \\callgraph + When this command is put in a comment block of a function or method + and \ref cfg_have_dot "HAVE_DOT" is set to YES, then doxygen will + generate a call graph for that function (provided the implementation of the + function or method calls other documented functions). The call graph will + generated regardless of the value of \ref cfg_call_graph "CALL_GRAPH". + \note The completeness (and correctness) of the call graph depends on the + doxygen code parser which is not perfect. + +
+\section cmdcallergraph \\callergraph + + \addindex \\callergraph + When this command is put in a comment block of a function or method + and \ref cfg_have_dot "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 \ref cfg_caller_graph "CALLER_GRAPH". + \note The completeness (and correctness) of the caller graph depends on the + doxygen code parser which is not perfect. + +
+\section cmdcategory \\category [] [] + + \addindex \\category + For Objective-C only: Indicates that a comment block contains documentation + for a class category with name \. The arguments are + equal to the \\class command. + + \sa section \ref cmdclass "\\class". + +
+\section cmdclass \\class [] [] + + \addindex \\class + Indicates that a comment block contains documentation for a + class with name \. 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 \ argument can be used to overwrite the + name of the link that is used in the class documentation to something other + than \. This can be useful if the include name is not located + on the default include path (like \). With the \ + 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 \ref cmdheaderfile "\\headerfile" command. + + \par Example: + \verbinclude class.h + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmddef \\def + + \addindex \\def + Indicates that a comment block contains documentation for a + \c \#define macro. + + \par Example: + \verbinclude define.h + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmddefgroup \\defgroup (group title) + + \addindex \\defgroup + Indicates that a comment block contains documentation for a + \ref modules "group" of classes, files or namespaces. This can be used to + categorize classes, files or namespaces, and document those + categories. You can also use groups as members of other groups, + thus building a hierarchy of groups. + + The \ argument should be a single-word identifier. + + \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup", + \ref cmdweakgroup "\\weakgroup". + +
+\section cmddir \\dir [] + + \addindex \\dir + 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 \ref cfg_show_dirs "SHOW_DIRECTORIES" option determines whether + or not the directory information is shown and the + \ref cfg_strip_from_path "STRIP_FROM_PATH" option determines what is + stripped from the full path before it appears in the output. + +
+\section cmdenum \\enum + + \addindex \\enum + Indicates that a comment block contains documentation for an + enumeration, with name \. If the enum is a member of a class and + the documentation block is located outside the class definition, + the scope of the class should be specified as well. + If a comment block is located directly in front of an enum declaration, + the \\enum comment may be omitted. + + \par Note: + The type of an anonymous enum cannot be documented, but the values + of an anonymous enum can. + + \par Example: + \verbinclude enum.h + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmdexample \\example + + \addindex \\example + Indicates that a comment block contains documentation for a source code + example. The name of the source file is \. 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 + \ref cfg_example_path "EXAMPLE_PATH" + tag of doxygen's configuration file. + + If \ itself is not unique for the set of example files specified + by the + \ref cfg_example_path "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. + + \par Example: + \verbinclude example.cpp + Where the example file \c example_test.cpp looks as follows: + \verbinclude example_test.cpp + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \sa section \ref cmdinclude "\\include". + +
+\section cmdextends \\extends + + \addindex \\extends + This command can be used to manually indicate an inheritance relation, + when the programming language does not support this concept natively + (e.g. C). + + The file \c manual.c in the example directory shows how to use this command. + + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \sa section \ref cmdimplements "\\implements" and section + \ref cmdmemberof "\\memberof" + +
+\section cmdfile \\file [] + + \addindex \\file + Indicates that a comment block contains documentation for a source or + header file with name \. The file name may include (part of) the + path if the file-name alone is not unique. If the file name is omitted + (i.e. the line after \\file is left blank) then the documentation block that + contains the \\file command will belong to the file it is located in. + + \par 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. + + \par Example: + \verbinclude file.h + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \note In the above example \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" + has been set to YES in the configuration file. + +
+\section cmdfn \\fn (function declaration) + + \addindex \\fn + Indicates that a comment block contains documentation for a function + (either global or as a member of a class). This command is \em only + needed if a comment block is \e not placed in front (or behind) + the function declaration or definition. + + If your comment block \e 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 specified after the + \\fn command on a \e 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. + + \par Example: + \verbinclude func.h + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + + \sa section \ref cmdvar "\\var" and \ref cmdtypedef "\\typedef". + +
+\section cmdheaderfile \\headerfile [] + + \addindex \\headerfile + 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 + \ref cmdclass "\\cmdclass". + 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 \ argument can be used to overwrite the + name of the link that is used in the class documentation to something other + than \. This can be useful if the include name is not located + on the default include path (like \). + + With the \ + argument you can also specify how the include statement should look like, + by adding either double quotes or sharp brackets around the name. + By default sharp brackets are used if just the name is given. + + If a pair of double quotes is given for either the header-file or + header-name argument, the current file (in which the command was found) + will be used but with quotes. So for a comment block with a \\headerfile + command inside a file test.h, the following three commands are equivalent: + \verbatim + \headerfile test.h "test.h" + \headerfile test.h "" + \headerfile "" \endverbatim + To get sharp brackets you do not need to specify anything, + but if you want to be explicit you could use any of the following: + \verbatim + \headerfile test.h + \headerfile test.h <> + \headerfile <> \endverbatim + + To globally reverse the default include representation to + local includes you can set + \ref cfg_force_local_includes "FORCE_LOCAL_INCLUDES" to \c YES. + + To disable the include information altogether set + \ref cfg_show_include_files "SHOW_INCLUDE_FILES" to \c NO. + +
+\section cmdhideinitializer \\hideinitializer + + \addindex \\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. + + \sa section \ref cmdshowinitializer "\\showinitializer". + +
+\section cmdimplements \\implements + + \addindex \\implements + This command can be used to manually indicate an inheritance relation, + when the programming language does not support this concept natively + (e.g. C). + + The file \c manual.c in the example directory shows how to use this command. + + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \sa section \ref cmdextends "\\extends" and section + \ref cmdmemberof "\\memberof" + +
+\section cmdingroup \\ingroup ( [ ]) + + \addindex \\ingroup + 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 \. + + \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", + \ref cmdaddtogroup "\\addtogroup" and \ref cmdweakgroup "\\weakgroup" + +
+\section cmdinterface \\interface [] [] + + \addindex \\interface + Indicates that a comment block contains documentation for an + interface with name \. The arguments are equal to the \\class + command. + + \sa section \ref cmdclass "\\class". + +
+\section cmdinternal \\internal + + \addindex \\internal + This command writes the message `For internal use only' to the output and + all text \e after an \c \\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 \ref cmdsection "\\section") all subsection after the + command are considered to be internal as well. Only a new section at the + same level will be visible again. + + You can use \ref cfg_internal_docs "INTERNAL_DOCS" in the config file + to show or hide the internal documentation. + +
+\section cmdmainpage \\mainpage [(title)] + + \addindex \\mainpage + + 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 \f$\mbox{\LaTeX}\f$). + + The title argument is optional and replaces the default title that + doxygen normally generates. If you do not want any title you can + specify \c notitle as the argument of \\mainpage. + + Here is an example: +\verbatim +/*! \mainpage My Personal Index Page + * + * \section intro_sec Introduction + * + * This is the introduction. + * + * \section install_sec Installation + * + * \subsection step1 Step 1: Opening the box + * + * etc... + */ +\endverbatim + + You can refer to the main page using \\ref index (if the treeview + is disabled, otherwise you should use \\ref main). + + \sa section \ref cmdsection "\\section", + section \ref cmdsubsection "\\subsection" and + section \ref cmdpage "\\page". + +
+\section cmdmemberof \\memberof + + \addindex \\memberof + This command make a function a member of a class in a similar way + as \ref cmdrelates "\\relates" does, only with this command the function + is represented as a real member of the class. + This can be useful when the programming language does not support + the concept of member functions natively (e.g. C). + + It is also possible to use this command together with + \ref cmdpublic "\\public", \ref cmdprotected "\\protected" or + \ref cmdprivate "\\private". + + The file \c manual.c in the example directory shows how to use this command. + + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \sa sections \ref cmdextends "\\extends", \ref cmdimplements "\\implements", + \ref cmdpublic "\\public", \ref cmdprotected "\\protected" and + \ref cmdprivate "\\private". + +
+\section cmdname \\name (header) + + \addindex \\name + + This command turns a comment block into a header + definition of a member group. The + comment block should be followed by a + //\@{ ... //\@} block containing the + members of the group. + + See section \ref memgroup for an example. + +
+\section cmdnamespace \\namespace + + \addindex \\namespace + Indicates that a comment block contains documentation for a + namespace with name \. + +
+\section cmdnosubgrouping \\nosubgrouping + + \addindex \\nosubgrouping + This command can be put in the documentation + of a class. It can be used in combination with member grouping + to avoid that doxygen puts a member group as a subgroup of a + Public/Protected/Private/... section. + +
+\section cmdoverload \\overload [(function declaration)] + + \addindex \\overload + 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. + + \par 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 + \ref cfg_sort_member_docs "SORT_MEMBER_DOCS" to NO in this case. + \par Note 2: + The \\overload command does not work inside a one-line comment. + \par Example: + \verbinclude examples/overload.cpp + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmdpackage \\package + + \addindex \\package + Indicates that a comment block contains documentation for a + Java package with name \. + +
+\section cmdpage \\page (title) + + \addindex \\page + 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 + \f$\mbox{\LaTeX}\f$ generator + starts a new section in the chapter `Page documentation'. + + \par Example: + \verbinclude page.doc + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \par Note: + The \ argument consists of a combination of letters and number + digits. If you wish to use upper case letters (e.g. \c MYPAGE1), or + mixed case letters (e.g. \c MyPage1) in the \ argument, you + should set \c CASE_SENSE_NAMES to \c 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. \c mypage1) + for \ in all references to the page. + + \sa section \ref cmdsection "\\section", section + \ref cmdsubsection "\\subsection", and section + \ref cmdref "\\ref". + +
+\section cmdprivate \\private + + \addindex \\private + \addindex \\privatesection + Indicates that the member documented in the comment block is private, + i.e., should only be accessed by other members in the same class. + + Note that Doxygen automatically detects the protection level of members + in object-oriented languages. This command is intended for use only when + the language does not support the concept of protection level natively + (e.g. C, PHP 4). + + For starting a section of private members, in a way similar to the + "private:" class marker in C++, use \\privatesection. + + \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public", + and \ref cmdprotected "\\protected". + +
+\section cmdproperty \\property (qualified property name) + + \addindex \\property + 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 \\fn. + + \sa section \ref cmdfn "\\fn" and \ref cmdvar "\\var". + +
+\section cmdprotected \\protected + + \addindex \\protected + \addindex \\protectedsection + Indicates that the member documented in the comment block is protected, + i.e., should only be accessed by other members in the same or derived + classes. + + Note that Doxygen automatically detects the protection level of members + in object-oriented languages. This command is intended for use only when + the language does not support the concept of protection level natively + (e.g. C, PHP 4). + + For starting a section of protected members, in a way similar to the + "protected:" class marker in C++, use \\protectedsection. + + \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public", + and \ref cmdprivate "\\private". + +
+\section cmdprotocol \\protocol [] [] + + \addindex \\protocol + Indicates that a comment block contains documentation for a + protocol in Objective-C with name \. The arguments are equal + to the \\class command. + + \sa section \ref cmdclass "\\class". + +
+\section cmdpublic \\public + + \addindex \\public + \addindex \\publicsection + Indicates that the member documented in the comment block is public, + i.e., can be accessed by any other class or function. + + Note that Doxygen automatically detects the protection level of members + in object-oriented languages. This command is intended for use only when + the language does not support the concept of protection level natively + (e.g. C, PHP 4). + + For starting a section of public members, in a way similar to the + "public:" class marker in C++, use \\publicsection. + + \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected" + and \ref cmdprivate "\\private". + +
+\section cmdrelates \\relates + + \addindex \\relates + This command can be used in the documentation of a non-member function + \. 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. + + \par Example: + \verbinclude relates.cpp + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmdrelatesalso \\relatesalso + + \addindex \\relatesalso + This command can be used in the documentation of a non-member function + \. It puts the function both inside the `related function' section + of the class documentation as well as leaving its normal file documentation + location. This command is useful for documenting + non-friend functions that are nevertheless strongly coupled to a certain + class. It only works for functions. + +
+\section cmdshowinitializer \\showinitializer + + \addindex \\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. + + \sa section \ref cmdhideinitializer "\\hideinitializer". + +
+\section cmdstruct \\struct [] [] + + \addindex \\struct + Indicates that a comment block contains documentation for a + struct with name \. The arguments are equal to the \\class + command. + + \sa section \ref cmdclass "\\class". + +
+\section cmdtypedef \\typedef (typedef declaration) + + \addindex \\typedef + 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. + + \sa section \ref cmdfn "\\fn" and \ref cmdvar "\\var". + +
+\section cmdunion \\union [] [] + + \addindex \\union + Indicates that a comment block contains documentation for a + union with name \. The arguments are equal to the \\class + command. + + \sa section \ref cmdclass "\\class". + +
+\section cmdvar \\var (variable declaration) + + \addindex \\var + 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. + + \sa section \ref cmdfn "\\fn" and \ref cmdtypedef "\\typedef". + +
+\section cmdweakgroup \\weakgroup [(title)] + \addindex \\addtogroup + Can be used exactly like \ref cmdaddtogroup "\\addtogroup", but has + a lower priority when it comes to resolving conflicting grouping + definitions. + + \sa page \ref grouping "Grouping" and \ref cmdaddtogroup "\\addtogroup". + +
+ +\htmlonly
\endhtmlonly +

+\htmlonly --- \endhtmlonly +Section indicators +\htmlonly --- \endhtmlonly +

+\htmlonly
\endhtmlonly + +
+\section cmdattention \\attention { attention text } + + \addindex \\attention + 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. + +
+\section cmdauthor \\author { list of authors } + + \addindex \\author + 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. + + \par Example: + \verbinclude author.cpp + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmdbrief \\brief {brief description} + + \addindex \\brief + 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 + \ref cmdauthor "\\author" for an example. + + Synonymous to \\short. + +
+\section cmdbug \\bug { bug description } + + \addindex \\bug + Starts a paragraph where one or more bugs may be reported. + The paragraph will be indented. + The text of the paragraph has no special internal structure. All visual + enhancement commands may be used inside the paragraph. + Multiple adjacent \\bug commands will be joined into a single paragraph. + Each bug description will start on a new line. + Alternatively, one \\bug command may mention + several bugs. The \\bug command ends when a blank line or some other + sectioning command is encountered. See section \ref cmdauthor "\\author" + for an example. + +
+\section cmdcond \\cond [] + + \addindex \\cond + Starts a conditional section that ends with a corresponding + \ref cmdendcond "\\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 \ref cfg_enabled_sections "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 \ref cmdif "\\if" ... \ref cmdendif "\\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: + +\verbatim +/** An interface */ +class Intf +{ + public: + /** A method */ + virtual void func() = 0; + + /// @cond TEST + + /** A method used for testing */ + virtual void test() = 0; + + /// @endcond +}; + +/// @cond DEV +/* + * The implementation of the interface + */ +class 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 +\endverbatim + +The output will be different depending on whether or not \c ENABLED_SECTIONS +contains \c TEST, or \c DEV + +
+\section cmddate \\date { date description } + + \addindex \\date + 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 \ref cmdauthor "\\author" + for an example. + +
+\section cmddeprecated \\deprecated { description } + + \addindex \\deprecated + Starts a paragraph indicating that this documentation block belongs to + a deprecated entity. Can be used to describe alternatives, + expected life span, etc. + +
+\section cmddetails \\details {detailed decription} + + \addindex \\details + Just like \ref cmdbrief "\\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. + +
+\section cmdelse \\else + + \addindex \\else + Starts a conditional section if the previous conditional section + was not enabled. The previous section should have been started with + a \c \\if, \c \\ifnot, or \c \\elseif command. + + \sa \ref cmdif "\\if", \ref cmdifnot "\\ifnot", \ref cmdelseif "\\elseif", + \ref cmdendif "\\endif." + +
+\section cmdelseif \\elseif + + \addindex \\elseif + 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 \ref cfg_enabled_sections "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. + + \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot", + \ref cmdelse "\\else", and \ref cmdelseif "\\elseif". + +
+\section cmdendcond \\endcond + + \addindex \\endcond + Ends a conditional section that was started by \ref cmdcond "\\cond". + + \sa \ref cmdcond "\\cond". + +
+\section cmdendif \\endif + + \addindex \\endif + Ends a conditional section that was started by \c \\if or \c \\ifnot + For each \c \\if or \c \\ifnot one and only one matching \c \\endif must follow. + + \sa \ref cmdif "\\if", and \ref cmdifnot "\\ifnot". + +
+\section cmdexception \\exception { exception description } + + \addindex \\exception + Starts an exception description for an exception object with name + \. 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 section \ref cmdfn "\\fn" for an + example. + + \par Note: + the tag \\exceptions is a synonym for this tag. + +
+\section cmdif \\if + + \addindex \\if + Starts a conditional documentation section. The section ends + with a matching \c \\endif command. A conditional section is + disabled by default. To enable it you must put the + section-label after the \ref cfg_enabled_sections "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. + + \par Example: +\verbatim + /*! Unconditionally shown documentation. + * \if Cond1 + * Only included if Cond1 is set. + * \endif + * \if Cond2 + * Only included if Cond2 is set. + * \if Cond3 + * Only included if Cond2 and Cond3 are set. + * \endif + * More text. + * \endif + * Unconditional text. + */ +\endverbatim + + You can also use conditional commands inside aliases. To + document a class in two languages you could for instance use: + +\par Example 2: +\verbatim +/*! \english + * This is English. + * \endenglish + * \dutch + * Dit is Nederlands. + * \enddutch + */ +class Example +{ +}; +\endverbatim + + Where the following aliases are defined in the configuration file: + +\verbatim +ALIASES = "english=\if english" \ + "endenglish=\endif" \ + "dutch=\if dutch" \ + "enddutch=\endif" +\endverbatim + + and \c ENABLED_SECTIONS can be used to enable either \c english or \c dutch. + + \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot", + \ref cmdelse "\\else", and \ref cmdelseif "\\elseif". + +
+\section cmdifnot \\ifnot + + \addindex \\ifnot + Starts a conditional documentation section. The section ends + with a matching \c \\endif command. This conditional section is + enabled by default. To disable it you must put the + section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS" + tag in the configuration + file. + + \sa sections \ref cmdendif "\\endif", \ref cmdif "\\if", + \ref cmdelse "\\else", and \ref cmdelseif "\\elseif". + +
+\section cmdinvariant \\invariant { description of invariant } + + \addindex \\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. + +
+\section cmdnote \\note { text } + + \addindex \\note + 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 \ref cmdpar "\\par" + for an example. + +
+\section cmdpar \\par [(paragraph title)] { paragraph } + + \addindex \\par + 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. + + \par Example: + \verbinclude par.cpp + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + +
+\section cmdparam \\param { parameter description } + + \addindex \\param + Starts a parameter description for a function parameter with name + \, 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 "in" and "out". Here is an example + for the function memcpy: + \code +/*! + * 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. + * @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); + \endcode + 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 commands may be used inside the paragraph. + + Multiple adjacent \\param commands will be joined into a single paragraph. + Each parameter description will start on a new line. + The \\param description ends when a blank line or some other + sectioning command is encountered. See section \ref cmdfn "\\fn" for an + example. + +
+\section cmdtparam \\tparam { description } + + \addindex \\tparam + Starts a template parameters for a class or function template parameter + with name \, followed by a description of the + template parameter. + + Otherwise similar to \ref cmdparam "\\cmdparam". + +
+\section cmdpost \\post { description of the postcondition } + + \addindex \\post + Starts a paragraph where the postcondition of an entity can be described. + The paragraph will be indented. + The text of the paragraph has no special internal structure. All visual + enhancement commands may be used inside the paragraph. + Multiple adjacent \\post commands will be joined into a single paragraph. + Each postcondition 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. + +
+\section cmdpre \\pre { description of the precondition } + + \addindex \\pre + 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. + +
+\section cmdremarks \\remarks { remark text } + + \addindex \\remarks + 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. + +
+\section cmdreturn \\return { description of the return value } + + \addindex \\return + 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 \ref cmdfn "\\fn" for an + example. + +
+\section cmdretval \\retval { description } + + \addindex \\retval + Starts a return value description for a function with name + \. 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. + +
+\section cmdsa \\sa { references } + + \addindex \\sa + 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. + + \sa section \ref autolink "autolink" for information on how to create links + to objects. + +
+\section cmdsee \\see { references } + + \addindex \\see + Equivalent to \ref cmdsa "\\sa". Introduced for compatibility with Javadoc. + +
+\section cmdsince \\since { text } + + \addindex \\since + 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. + +
+\section cmdtest \\test { paragraph describing a test case } + + \addindex \\test + 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. + +
+\section cmdthrow \\throw { exception description } + + \addindex \\throw + Synonymous to \\exception (see section \ref cmdexception "\\exception"). + + \par Note: + the tag \\throws is a synonym for this tag. + +
+\section cmdtodo \\todo { paragraph describing what is to be done } + + \addindex \\todo + 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. + +
+\section cmdversion \\version { version number } + + \addindex \\version + Starts a paragraph where one or more version strings 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 \\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 \ref cmdauthor "\\author" + for an example. + +
+\section cmdwarning \\warning { warning message } + + \addindex \\warning + 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 \ref cmdauthor "\\author" + for an example. + +
+\section cmdxrefitem \\xrefitem "(heading)" "(list title)" {text} + + \addindex \\xrefitem + This command is a generalization of commands such as \ref cmdtodo "\\todo" + and \ref cmdbug "\\bug". + It can be used to create user-defined text sections which are automatically + cross-referenced between the place of occurrence and a related page, + which will be generated. On the related page all sections of + the same type will be collected. + + The first argument \ is a + identifier uniquely representing the type of the section. 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 + \verbatim \xrefitem todo "Todo" "Todo List" \endverbatim + + 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 \ref cfg_aliases "ALIASES" option in the + configuration file. + To define a new command \\reminder, for instance, one should add the following + line to the configuration file: + \verbatim ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" \endverbatim + Note the use of escaped quotes for the second and third argument of the + \\xrefitem command. + +
+ +\htmlonly
\endhtmlonly +

+\htmlonly --- \endhtmlonly +Commands to create links +\htmlonly --- \endhtmlonly +

+\htmlonly
\endhtmlonly + +
+\section cmdaddindex \\addindex (text) + + \addindex \\addindex + This command adds (text) to the \f$\mbox{\LaTeX}\f$ index. + +
+\section cmdanchor \\anchor + + \addindex \\anchor + 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 \ref cmdpage "\\page") or mainpage + (\ref cmdmainpage "\\mainpage"). + + \sa section \ref cmdref "\\ref". + +
+\section cmdendlink \\endlink + + \addindex \\endlink + This command ends a link that is started with the \\link command. + + \sa section \ref cmdlink "\\link". + +
+\section cmdlink \\link + + \addindex \\link + The links that are automatically generated by doxygen always have the + name of the object they point to as link-text. + + The \\link command can be used to create a link to an object (a file, + class, or member) with a user specified link-text. + The link command should end with an \\endlink command. All text between + the \\link and \\endlink commands serves as text for a link to + the \ specified as the first argument of \\link. + + See section \ref autolink "autolink" for more information on automatically + generated links and valid link-objects. + +
+\section cmdref \\ref ["(text)"] + + \addindex \\ref + 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 \ if no text is specified. + For \f$\mbox{\LaTeX}\f$ documentation the reference command will + generate a section number for sections or the text followed by a + page number if \ refers to an anchor. + + \sa + Section \ref cmdpage "\\page" for an example of the \\ref command. + +
+\section cmdsubpage \\subpage ["(text)"] + + \addindex \\subpage + This command can be used to create a hierarchy of pages. The + same structure can be made using the \ref cmddefgroup "\\defgroup" and + \ref cmdingroup "\\ingroup" commands, but for pages the \\subpage command + is often more convenient. The main page (see \ref cmdmainpage "\\mainpage") + is typically the root of hierarchy. + + This command behaves similar as \ref cmdref "\\ref" in the sense that + it creates a reference to a page labeled \ 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 \. + + See the \ref cmdsection "\\section" + and \ref cmdsubsection "\\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: +\verbatim +/*! \mainpage A simple manual + +Some general info. + +This manual is divided in the following sections: +- \subpage intro +- \subpage advanced "Advanced usage" +*/ + +//----------------------------------------------------------- + +/*! \page intro Introduction +This page introduces the user to the topic. +Now you can proceed to the \ref advanced "advanced section". +*/ + +//----------------------------------------------------------- + +/*! \page advanced Advanced Usage +This page is for advanced users. +Make sure you have first read \ref intro "the introduction". +*/ +\endverbatim + +
+\section cmdsection \\section (section title) + + \addindex \\section + Creates a section with name \. 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 + \e not in other documentation blocks! + +
+\section cmdsubsection \\subsection (subsection title) + + \addindex \\subsection + Creates a subsection with name \. 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 + \e not in other documentation blocks! + + \sa + Section \ref cmdpage "\\page" for an example of the + \ref cmdsubsection "\\subsection" command. + +
+\section cmdsubsubsection \\subsubsection (subsubsection title) + + \addindex \\subsubsection + Creates a subsubsection with name \. 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 + \e not in other documentation blocks! + + \sa + Section \ref cmdpage "\\page" for an example of the + \ref cmdsubsubsection "\\subsubsection" command. + +
+\section cmdparagraph \\paragraph (paragraph title) + + \addindex \\paragraph + Creates a named paragraph with name \. 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 + \e not in other documentation blocks! + + \sa + Section \ref cmdpage "\\page" for an example of the + \ref cmdparagraph "\\paragraph" command. + +
+ +\htmlonly
\endhtmlonly +

+\htmlonly --- \endhtmlonly +Commands for displaying examples +\htmlonly --- \endhtmlonly +

+\htmlonly
\endhtmlonly + +
+\section cmddontinclude \\dontinclude + + \addindex \\dontinclude + 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 + \ref cfg_example_path "EXAMPLE_PATH" + tag of doxygen's configuration file. + + The class and member declarations and definitions inside the code fragment + are `remembered' during the parsing of the comment block that contained + the \\dontinclude command. + + For line by line descriptions of source files, one or more lines + of the example can be displayed using the \\line, \\skip, \\skipline, and + \\until commands. An internal pointer is used for these commands. The + \\dontinclude command sets the pointer to the first line of the example. + + \par Example: + \verbinclude include.cpp + Where the example file \c example_test.cpp looks as follows: + \verbinclude example_test.cpp + \htmlonly + Click here + for the corresponding HTML documentation that is generated by doxygen. + \endhtmlonly + + \sa sections \ref cmdline "\\line", \ref cmdskip "\\skip", + \ref cmdskipline "\\skipline", and \ref cmduntil "\\until". + +
+\section cmdinclude \\include + + \addindex \\include + 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 + \ref cfg_example_path "EXAMPLE_PATH" + tag of doxygen's configuration file. + + If \ itself is not unique for the set of example files specified + by the \ref cfg_example_path "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 surrounding it + with \ref cmdcode "\\code" and \ref cmdendcode "\\endcode" commands. + + 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 + \ref cmddontinclude "\\dontinclude" command in combination with + the \ref cmdline "\\line", \ref cmdskip "\\skip", + \ref cmdskipline "\\skipline", + and \\until commands. + + \note Doxygen's special commands do not work inside blocks of code. + It is allowed to nest C-style comments inside a code block though. + + \sa section \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude", and + section \ref cmdverbatim "\\verbatim". + +
+\section cmdincludelineno \\includelineno + + \addindex \\includelineno + This command works the same way as \\include, but will add line + numbers to the included file. + + \sa section \ref cmdinclude "\\include". + +
+\section cmdline \\line ( pattern ) + + \addindex \\line + This command searches line by line through the example that was last + included using \\include or \\dontinclude until it finds a non-blank + line. If that line contains the specified pattern, it is written + to the output. + + The internal pointer that is used to keep track of the current line in + the example, is set to the start of the line following the non-blank + line that was found (or to the end of the example if no such line could + be found). + + See section \ref cmddontinclude "\\dontinclude" for an example. + +
+\section cmdskip \\skip ( pattern ) + + \addindex \\skip + 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 \ref cmddontinclude "\\dontinclude" for an example. + +
+\section cmdskipline \\skipline ( pattern ) + + \addindex \\skipline + 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). + + \par Note: + The command: + \verbatim\skipline pattern\endverbatim + is equivalent to: +\verbatim +\skip pattern +\line pattern\endverbatim + + See section \ref cmddontinclude "\\dontinclude" for an example. + +
+\section cmduntil \\until ( pattern ) + + \addindex \\until + 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 \ref cmddontinclude "\\dontinclude" for an example. + +
+\section cmdverbinclude \\verbinclude + + \addindex \\verbinclude + This command includes the file \ 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 + \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. + +
+\section cmdhtmlinclude \\htmlinclude + + \addindex \\htmlinclude + This command includes the file \ as is in the HTML documentation. + The command is equivalent 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 + \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. + +
+ +\htmlonly
\endhtmlonly +

+\htmlonly --- \endhtmlonly +Commands for visual enhancements +\htmlonly --- \endhtmlonly +

+\htmlonly
\endhtmlonly + +\section cmda \\a + + \addindex \\a + Displays the argument \ using a special font. + Use this command to refer to member arguments in the running text. + + \par Example: + \verbatim + ... the \a x and \a y coordinates are used to ... + \endverbatim + This will result in the following text:

+ ... the \a x and \a y coordinates are used to ... + +
+\section cmdarg \\arg { item-description } + + \addindex \\arg + 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. + + \par Example: + Typing: + \verbatim + \arg \c AlignLeft left alignment. + \arg \c AlignCenter center alignment. + \arg \c AlignRight right alignment + + No other types of alignment are supported. + \endverbatim + will result in the following text:

+
    +
  • \c AlignLeft left alignment. +
  • \c AlignCenter center alignment. +
  • \c AlignRight right alignment +

+ No other types of alignment are supported. + + \par Note: + For nested lists, HTML commands should be used. + + Equivalent to \ref cmdli "\\li" + + +
+\section cmdb \\b + + \addindex \\b + Displays the argument \ using a bold font. + Equivalent to \word\. + To put multiple words in bold use \multiple words\. + +
+\section cmdc \\c + + \addindex \\c + Displays the argument \ using a typewriter font. + Use this to refer to a word of code. + Equivalent to \word\. + + \par Example: + Typing: + \verbatim + ... This function returns \c void and not \c int ... + \endverbatim + will result in the following text:

+ ... This function returns \c void and not \c int ... + + Equivalent to \ref cmdp "\\p" + To have multiple words in typewriter font use \multiple words\. + +
+\section cmdcode \\code + + \addindex \\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. + + \sa section \ref cmdendcode "\\endcode", section \ref cmdverbatim "\\verbatim". + +
+\section cmdcopydoc \\copydoc + + \addindex \\copydoc + Copies a documentation block from the object specified by \ + 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 documentation + +\verbatim + /*! @copydoc MyClass::myfunction() + * More documentation. + */ +\endverbatim + + if the member is overloaded, you should specify the argument types + explicitly (without spaces!), like in the following: + +\verbatim + /*! @copydoc MyClass::myfunction(type1,type2) */ +\endverbatim + + 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 \ref cmdcopybrief "\\cmdcopybrief" and + \ref cmdcopydetails "\\cmdcopydetails" for copying only the brief or + detailed part of the comment block. + +
+\section cmdcopybrief \\copybrief + +Works in a similar way as \ref cmdcopydoc "\\copydoc" but will +only copy the brief description, not the detailed documentation. + +
+\section cmdcopydetails \\copydetails + +Works in a similar way as \ref cmdcopydoc "\\copydoc" but will +only copy the detailed documentation, not the brief description. + +
+\section cmddot \\dot + + \addindex \\dot + Starts a text fragment which should contain a valid description of a + dot graph. The text fragment ends with \ref cmdenddot "\\enddot". + Doxygen will pass the text on to dot and include the resulting + image (and image map) into the 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: +\code +/*! class B */ +class B {}; + +/*! class C */ +class C {}; + +/*! \mainpage + * + * Class relations expressed via an inline dot graph: + * \dot + * digraph example { + * node [shape=record, fontname=Helvetica, fontsize=10]; + * b [ label="class B" URL="\ref B"]; + * c [ label="class C" URL="\ref C"]; + * b -> c [ arrowhead="open", style="dashed" ]; + * } + * \enddot + * Note that the classes in the above graph are clickable + * (in the HTML output). + */ +\endcode + +
+\section cmdmsc \\msc + + \addindex \\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 \ref cmdendmsc "\\endmsc". + \note The text fragment should only include the part of the message + sequence chart that is + within the msc {...} block. + \note 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. +\code +/** 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->Receiver [label="Command()", URL="\ref Receiver::Command()"]; + * Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"]; + * \endmsc + */ +class Sender +{ + public: + /** Acknowledgement from server */ + void Ack(bool ok); +}; + +/** 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"]; + * \endmsc + */ +class Receiver +{ + public: + /** Executable a command on the server */ + void Command(int commandId); +}; + +\endcode + +
+\section cmddotfile \\dotfile ["caption"] + + \addindex \\dotfile + Inserts an image generated by dot from \ 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 \ref cfg_dotfile_dirs "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. + +
+\section cmde \\e + + \addindex \\e + Displays the argument \ in italics. + Use this command to emphasize words. + + \par Example: + Typing: + \verbatim + ... this is a \e really good example ... + \endverbatim + will result in the following text:

+ ... this is a \e really good example ... + + Equivalent to \ref cmdem "\\em". + To emphasis multiple words use \multiple words\. + +
+\section cmdem \\em + + \addindex \\em + Displays the argument \ in italics. + Use this command to emphasize words. + + \par Example: + Typing: + \verbatim + ... this is a \em really good example ... + \endverbatim + will result in the following text:

+ ... this is a \em really good example ... + + Equivalent to \ref cmde "\\e" + +
+\section cmdendcode \\endcode + + \addindex \\endcode + Ends a block of code. + \sa section \ref cmdcode "\\code" + +
+\section cmdenddot \\enddot + + \addindex \\enddot + Ends a blocks that was started with \ref cmddot "\\dot". + +
+\section cmdendmsc \\endmsc + + \addindex \\endmsc + Ends a blocks that was started with \ref cmdmsc "\\msc". + +
+\section cmdendhtmlonly \\endhtmlonly + + \addindex \\endhtmlonly + Ends a block of text that was started with a \\htmlonly command. + + \sa section \ref cmdhtmlonly "\\htmlonly". + +
+\section cmdendlatexonly \\endlatexonly + + \addindex \\endlatexonly + Ends a block of text that was started with a \\latexonly command. + + \sa section \ref cmdlatexonly "\\latexonly". + +
+\section cmdendmanonly \\endmanonly + + \addindex \\endmanonly + Ends a block of text that was started with a \\manonly command. + + \sa section \ref cmdmanonly "\\manonly". + +
+\section cmdendverbatim \\endverbatim + + \addindex \\endverbatim + Ends a block of text that was started with a \\verbatim command. + + \sa section \ref cmdendcode "\\endcode", section \ref cmdverbatim "\\verbatim". + +
+\section cmdendxmlonly \\endxmlonly + + \addindex \\endxmlonly + Ends a block of text that was started with a \\xmlonly command. + + \sa section \ref cmdxmlonly "\\xmlonly". + +
+\section cmdfdollar \\f$ + + \addindex \\f\$ + + Marks the start and end of an in-text formula. + \sa section \ref formulas "formulas" for an example. + +
+\section cmdfbropen \\f[ + + \addindex \\f[ + + Marks the start of a long formula that is displayed + centered on a separate line. + \sa section \ref cmdfbrclose "\\f]" and section \ref formulas "formulas". + +
+\section cmdfbrclose \\f] + + \addindex \\f] + + Marks the end of a long formula that is displayed + centered on a separate line. + \sa section \ref cmdfbropen "\\f[" and section \ref formulas "formulas". + +
+\section cmdfcurlyopen \\f{environment}{ + + Marks the start of a formula that is in a specific environment. + \note The second \{ is optional and is only to help editors (such as Vim) to + do proper syntax highlighting by making the number of opening and closing braces + the same. + +
+\section cmdfcurlyclose \\f} + + Marks the end of a formula that is in a specific environment. + +
+\section cmdhtmlonly \\htmlonly + + \addindex \\htmlonly + Starts a block of text that will be verbatim included in the + generated HTML documentation only. The block ends with a + endhtmlonly command. + + This command can be used to include HTML code that is too complex + for doxygen (i.e. applets, java-scripts, and HTML tags that + require attributes). You can use the \\latexonly and \\endlatexonly + pair to provide a proper \f$\mbox{\LaTeX}\f$ alternative. + + \b Note: + environment variables (like \$(HOME) ) are resolved inside a + HTML-only block. + + \sa section \ref cmdmanonly "\\manonly" and section + \ref cmdlatexonly "\\latexonly". + +
+\section cmdimage \\image ["caption"] [=] + + \addindex \\image + 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: \c html and \c 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 \ref cfg_image_path "IMAGE_PATH" tag. + If the image is found it will be copied to the correct output directory. + If the image name contains spaces you'll have to put quotes ("...") around it. + You can also specify an absolute URL instead of a file name, but then + doxygen does not copy the image nor check its existance. + + The third argument is optional and can be used to specify the caption + that is displayed below the image. This argument has to be specified + 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 \f$\mbox{\LaTeX}\f$ output + (i.e. format=latex). The \c sizeindication can be + either \c width or \c height. The size should be a valid + size specifier in \f$\mbox{\LaTeX}\f$ (for example 10cm or + 6in or a symbolic width like \\textwidth). + + Here is example of a comment block: + +\verbatim + /*! Here is a snapshot of my new application: + * \image html application.jpg + * \image latex application.eps "My application" width=10cm + */ +\endverbatim + + And this is an example of how the relevant part of the configuration file + may look: + +\verbatim + IMAGE_PATH = my_image_dir +\endverbatim + + \warning The image format for HTML is limited to what your + browser supports. For \f$\mbox{\LaTeX}\f$, the image format + must be Encapsulated PostScript (eps). +

+ Doxygen does not check if the image is in the correct format. + So \e you have to make sure this is the case! + +
+\section cmdlatexonly \\latexonly + + \addindex \\latexonly + Starts a block of text that will be verbatim included in the + generated \f$\mbox{\LaTeX}\f$ documentation only. The block ends with a + endlatexonly command. + + This command can be used to include \f$\mbox{\LaTeX}\f$ code that is too + complex for doxygen (i.e. images, formulas, special characters). You can + use the \\htmlonly and \\endhtmlonly pair to provide a proper HTML + alternative. + + \b Note: + environment variables (like \$(HOME) ) are resolved inside a + \f$\mbox{\LaTeX}\f$-only block. + + \sa section \ref cmdlatexonly "\\latexonly" + and section \ref cmdhtmlonly "\\htmlonly". + +
+\section cmdmanonly \\manonly + + \addindex \\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 \\latexonly and + \\endhtmlonly and \\endlatexonly pairs to provide proper + HTML and \f$\mbox{\LaTeX}\f$ alternatives. + + \sa section \ref cmdhtmlonly "\\htmlonly" and section + \ref cmdlatexonly "\\latexonly". + +
+\section cmdli \\li { item-description } + + \addindex \\li + This command has one argument that continues until the first + blank line or until another \\li is encountered. + The command can be used to generate a simple, not nested list of + arguments. + Each argument should start with a \\li command. + + \par Example: + Typing: + \verbatim + \li \c AlignLeft left alignment. + \li \c AlignCenter center alignment. + \li \c AlignRight right alignment + + No other types of alignment are supported. + \endverbatim + will result in the following text:

+
    +
  • \c AlignLeft left alignment. +
  • \c AlignCenter center alignment. +
  • \c AlignRight right alignment +

+ No other types of alignment are supported. + + \par Note: + For nested lists, HTML commands should be used. + + Equivalent to \ref cmdarg "\\arg" + +
+\section cmdn \\n + + \addindex \\n + Forces a new line. Equivalent to \ and inspired by + the printf function. + +
+\section cmdp \\p + + \addindex \\p + Displays the parameter \ using a typewriter font. + You can use this command to refer to member function parameters in + the running text. + + \par Example: + \verbatim + ... the \p x and \p y coordinates are used to ... + \endverbatim + This will result in the following text:

+ ... the \p x and \p y coordinates are used to ... + + Equivalent to \ref cmdc "\\c" + +
+\section cmdverbatim \\verbatim + + \addindex \\verbatim + Starts a block of text that will be verbatim included in both the + HTML and the + \f$\mbox{\LaTeX}\f$ 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! + + \sa section \ref cmdcode "\\code", and section \ref cmdverbinclude "\\verbinclude". + +
+\section cmdxmlonly \\xmlonly + + \addindex \\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. + + \sa section \ref cmdhtmlonly "\\htmlonly" and section + \ref cmdlatexonly "\\latexonly". + +
+\section cmdbackslash \\\\ + + \addindex \\\\ + This command writes a backslash character (\\) to the HTML and + \f$\mbox{\LaTeX}\f$ output. The backslash has to be escaped in some + cases because doxygen uses it to detect commands. + +
+\section cmdat \\\@ + + \addindex \\\@ + This command writes an at-sign (\@) to the HTML and + \f$\mbox{\LaTeX}\f$ output. The at-sign has to be escaped in some cases + because doxygen uses it to detect JavaDoc commands. + +
+\section cmdtilde \\~[LanguageId] + \addindex \\~ + 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 \c 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: +\verbatim +/*! \~english This is english \~dutch Dit is Nederlands \~german Dieses ist + deutsch. \~ output for all languages. + */ +\endverbatim + + +
+\section cmdamp \\\& + + \addindex \\\& + This command writes the \& character to output. + This character has to be escaped because it has a special meaning in HTML. + +
+\section cmddollar \\\$ + + \addindex \\\$ + This command writes the \$ character to the output. + This character has to be escaped in some cases, because it is used to expand + environment variables. + +
+\section cmdhash \\\# + + \addindex \\\# + 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. + +
+\section cmdlt \\\< + + \addindex \\\< + This command writes the \< character to the output. + This character has to be escaped because it has a special meaning in HTML. + +
+\section cmdgt \\\> + + \addindex \\\> + This command writes the \> character to the output. This + character has to be escaped because it has a special meaning in HTML. + +
+\section cmdperc \\\% + + \addindex \\\% + This command writes 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. + +
+\section cmdquot \\" + + \addindex \\\" + This command writes the \" character to the output. This + character has to be escaped in some cases, because it is used in pairs + to indicate an unformated text fragment. + +
+\htmlonly
\endhtmlonly +

+\htmlonly --- \endhtmlonly +Commands included for Qt compatibility +\htmlonly --- \endhtmlonly +

+\htmlonly
\endhtmlonly + +The following commands are supported to remain compatible to the Qt class +browser generator. Do \e not use these commands in your own documentation. +
    +
  • \\annotatedclasslist +
  • \\classhierarchy +
  • \\define +
  • \\functionindex +
  • \\header +
  • \\headerfilelist +
  • \\inherit +
  • \\l +
  • \\postheader +
+
+ +*/ +