1 /******************************************************************************
5 * Copyright (C) 1997-2014 by Dimitri van Heesch.
7 * Permission to use, copy, modify, and distribute this software and its
8 * documentation under the terms of the GNU General Public License is hereby
9 * granted. No representations are made about the suitability of this software
10 * for any purpose. It is provided "as is" without express or implied warranty.
11 * See the GNU General Public License for more details.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page commands Special Commands
19 \section cmd_intro Introduction
21 All commands in the documentation start with a backslash (<b>\\</b>) or an
22 at-sign (<b>\@</b>). If you prefer you can replace all commands starting with a
23 backslash below by their counterparts that start with an at-sign.
25 Some commands have one or more arguments.
26 Each argument has a certain range:
28 <li>If \<sharp\> braces are used the argument is a single word.
29 <li>If (round) braces are used the argument extends until the end of the line
30 on which the command was found.
31 <li>If {curly} braces are used the argument extends until the next paragraph.
32 Paragraphs are delimited by a blank line or by a section indicator.
34 If in addition to the above argument specifiers [square] brackets are used the argument is optional.
36 Here is an alphabetically sorted list of all commands with references to their
38 \anchor showsecreflist
41 \refitem cmdaddindex \\addindex
42 \refitem cmdaddtogroup \\addtogroup
43 \refitem cmdanchor \\anchor
45 \refitem cmdattention \\attention
46 \refitem cmdauthor \\author
47 \refitem cmdauthors \\authors
49 \refitem cmdbrief \\brief
52 \refitem cmdcallgraph \\callgraph
53 \refitem cmdcallergraph \\callergraph
54 \refitem cmdcategory \\category
55 \refitem cmdcite \\cite
56 \refitem cmdclass \\class
57 \refitem cmdcode \\code
58 \refitem cmdcond \\cond
59 \refitem cmdcopybrief \\copybrief
60 \refitem cmdcopydetails \\copydetails
61 \refitem cmdcopydoc \\copydoc
62 \refitem cmdcopyright \\copyright
63 \refitem cmddate \\date
65 \refitem cmddefgroup \\defgroup
66 \refitem cmddeprecated \\deprecated
67 \refitem cmddetails \\details
68 \refitem cmddiafile \\diafile
70 \refitem cmddocbookonly \\docbookonly
71 \refitem cmddontinclude \\dontinclude
73 \refitem cmddotfile \\dotfile
75 \refitem cmdelse \\else
76 \refitem cmdelseif \\elseif
78 \refitem cmdendcode \\endcode
79 \refitem cmdendcond \\endcond
80 \refitem cmdenddocbookonly \\enddocbookonly
81 \refitem cmdenddot \\enddot
82 \refitem cmdendhtmlonly \\endhtmlonly
83 \refitem cmdendif \\endif
84 \refitem cmdendinternal \\endinternal
85 \refitem cmdendlatexonly \\endlatexonly
86 \refitem cmdendlink \\endlink
87 \refitem cmdendmanonly \\endmanonly
88 \refitem cmdendmsc \\endmsc
89 \refitem cmdendparblock \\endparblock
90 \refitem cmdendrtfonly \\endrtfonly
91 \refitem cmdendsecreflist \\endsecreflist
92 \refitem cmdendverbatim \\endverbatim
93 \refitem cmdenduml \\enduml
94 \refitem cmdendxmlonly \\endxmlonly
95 \refitem cmdenum \\enum
96 \refitem cmdexample \\example
97 \refitem cmdexception \\exception
98 \refitem cmdextends \\extends
99 \refitem cmdfdollar \\f\$
100 \refitem cmdfbropen \\f[
101 \refitem cmdfbrclose \\f]
102 \refitem cmdfcurlyopen \\f{
103 \refitem cmdfcurlyclose \\f}
104 \refitem cmdfile \\file
106 \refitem cmdheaderfile \\headerfile
107 \refitem cmdhideinitializer \\hideinitializer
108 \refitem cmdhtmlinclude \\htmlinclude
109 \refitem cmdhtmlonly \\htmlonly
110 \refitem cmdidlexcept \\idlexcept
112 \refitem cmdifnot \\ifnot
113 \refitem cmdimage \\image
114 \refitem cmdimplements \\implements
115 \refitem cmdinclude \\include
116 \refitem cmdincludelineno \\includelineno
117 \refitem cmdingroup \\ingroup
118 \refitem cmdinternal \\internal
119 \refitem cmdinvariant \\invariant
120 \refitem cmdinterface \\interface
121 \refitem cmdlatexinclude \\latexinclude
122 \refitem cmdlatexonly \\latexonly
124 \refitem cmdline \\line
125 \refitem cmdlink \\link
126 \refitem cmdmainpage \\mainpage
127 \refitem cmdmanonly \\manonly
128 \refitem cmdmemberof \\memberof
129 \refitem cmdmsc \\msc
130 \refitem cmdmscfile \\mscfile
132 \refitem cmdname \\name
133 \refitem cmdnamespace \\namespace
134 \refitem cmdnosubgrouping \\nosubgrouping
135 \refitem cmdnote \\note
136 \refitem cmdoverload \\overload
138 \refitem cmdpackage \\package
139 \refitem cmdpage \\page
140 \refitem cmdpar \\par
141 \refitem cmdparagraph \\paragraph
142 \refitem cmdparam \\param
143 \refitem cmdparblock \\parblock
144 \refitem cmdpost \\post
145 \refitem cmdpre \\pre
146 \refitem cmdprivate \\private
147 \refitem cmdprivatesection \\privatesection
148 \refitem cmdproperty \\property
149 \refitem cmdprotected \\protected
150 \refitem cmdprotectedsection \\protectedsection
151 \refitem cmdprotocol \\protocol
152 \refitem cmdpublic \\public
153 \refitem cmdpublicsection \\publicsection
154 \refitem cmdpure \\pure
155 \refitem cmdref \\ref
156 \refitem cmdrefitem \\refitem
157 \refitem cmdrelated \\related
158 \refitem cmdrelates \\relates
159 \refitem cmdrelatedalso \\relatedalso
160 \refitem cmdrelatesalso \\relatesalso
161 \refitem cmdremark \\remark
162 \refitem cmdremarks \\remarks
163 \refitem cmdresult \\result
164 \refitem cmdreturn \\return
165 \refitem cmdreturns \\returns
166 \refitem cmdretval \\retval
167 \refitem cmdrtfonly \\rtfonly
169 \refitem cmdsecreflist \\secreflist
170 \refitem cmdsection \\section
171 \refitem cmdsee \\see
172 \refitem cmdshort \\short
173 \refitem cmdshowinitializer \\showinitializer
174 \refitem cmdsince \\since
175 \refitem cmdskip \\skip
176 \refitem cmdskipline \\skipline
177 \refitem cmdsnippet \\snippet
178 \refitem cmdstartuml \\startuml
179 \refitem cmdstruct \\struct
180 \refitem cmdsubpage \\subpage
181 \refitem cmdsubsection \\subsection
182 \refitem cmdsubsubsection \\subsubsection
183 \refitem cmdtableofcontents \\tableofcontents
184 \refitem cmdtest \\test
185 \refitem cmdthrow \\throw
186 \refitem cmdthrows \\throws
187 \refitem cmdtodo \\todo
188 \refitem cmdtparam \\tparam
189 \refitem cmdtypedef \\typedef
190 \refitem cmdunion \\union
191 \refitem cmduntil \\until
192 \refitem cmdvar \\var
193 \refitem cmdverbatim \\verbatim
194 \refitem cmdverbinclude \\verbinclude
195 \refitem cmdversion \\version
196 \refitem cmdvhdlflow \\vhdlflow
197 \refitem cmdwarning \\warning
198 \refitem cmdweakgroup \\weakgroup
199 \refitem cmdxmlonly \\xmlonly
200 \refitem cmdxrefitem \\xrefitem
201 \refitem cmddollar \\\$
203 \refitem cmdbackslash \\\\
205 \refitem cmdtilde \\~
208 \refitem cmdhash \\\#
209 \refitem cmdperc \\\%
210 \refitem cmdquot \\\"
211 \refitem cmdchardot \\\.
212 \refitem cmddcolon \::
214 \refitem cmdndash \\\--
215 \refitem cmdmdash \\\---
218 The following subsections provide a list of all commands that are recognized by
219 doxygen. Unrecognized commands are treated as normal text.
222 \htmlonly <center> \endhtmlonly
224 \htmlonly --- \endhtmlonly
225 Structural indicators
226 \htmlonly --- \endhtmlonly
228 \htmlonly </center> \endhtmlonly
230 \section cmdaddtogroup \\addtogroup <name> [(title)]
231 \addindex \\addtogroup
232 Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to
233 that command using the same \<name\> more than once will not result in a warning,
234 but rather one group with a merged documentation and the first title found in
237 The title is optional, so this command can also be used to add a number of
238 entities to an existing group using \c \@{ and \c \@} like this:
241 /*! \addtogroup mygrp
242 * Additional documentation for group 'mygrp'
253 /*! Another function */
261 \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup", and
262 \ref cmdweakgroup "\\weakgroup".
265 \section cmdcallgraph \\callgraph
267 \addindex \\callgraph
268 When this command is put in a comment block of a function or method
269 and \ref cfg_have_dot "HAVE_DOT" is set to \c YES, then doxygen will
270 generate a call graph for that function (provided the implementation of the
271 function or method calls other documented functions). The call graph will be
272 generated regardless of the value of \ref cfg_call_graph "CALL_GRAPH".
273 \note The completeness (and correctness) of the call graph depends on the
274 doxygen code parser which is not perfect.
276 \sa section \ref cmdcallergraph "\\callergraph".
279 \section cmdcallergraph \\callergraph
281 \addindex \\callergraph
282 When this command is put in a comment block of a function or method
283 and \ref cfg_have_dot "HAVE_DOT" is set to \c YES, then doxygen will
284 generate a caller graph for that function (provided the implementation of the
285 function or method calls other documented functions). The caller graph will be
286 generated regardless of the value of \ref cfg_caller_graph "CALLER_GRAPH".
287 \note The completeness (and correctness) of the caller graph depends on the
288 doxygen code parser which is not perfect.
290 \sa section \ref cmdcallgraph "\\callgraph".
293 \section cmdcategory \\category <name> [<header-file>] [<header-name>]
296 For Objective-C only: Indicates that a comment block contains documentation
297 for a class category with name \<name\>. The arguments are
298 equal to the \ref cmdclass "\\class" command.
300 \sa section \ref cmdclass "\\class".
303 \section cmdclass \\class <name> [<header-file>] [<header-name>]
306 Indicates that a comment block contains documentation for a
307 class with name \<name\>. Optionally a header file and a header name
308 can be specified. If the header-file is specified, a link to a verbatim copy
309 of the header will be included in the HTML documentation.
310 The \<header-name\> argument can be used to overwrite the
311 name of the link that is used in the class documentation to something other
312 than \<header-file\>. This can be useful if the include name is not located
313 on the default include path (like \<X11/X.h\>). With the \<header-name\>
314 argument you can also specify how the include statement should look like,
315 by adding either quotes or sharp brackets around the name.
316 Sharp brackets are used if just the name is given. Note that the
317 last two arguments can also be specified using
318 the \ref cmdheaderfile "\\headerfile" command.
323 Click <a href="$(DOXYGEN_DOCDIR)/examples/class/html/index.html">here</a>
324 for the corresponding HTML documentation that is generated by doxygen.
328 \section cmddef \\def <name>
331 Indicates that a comment block contains documentation for a
335 \verbinclude define.h
337 Click <a href="$(DOXYGEN_DOCDIR)/examples/define/html/define_8h.html">here</a>
338 for the corresponding HTML documentation that is generated by doxygen.
342 \section cmddefgroup \\defgroup <name> (group title)
345 Indicates that a comment block contains documentation for a
346 \ref modules "group" of classes, files or namespaces. This can be used to
347 categorize classes, files or namespaces, and document those
348 categories. You can also use groups as members of other groups,
349 thus building a hierarchy of groups.
351 The \<name\> argument should be a single-word identifier.
353 \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup", and
354 \ref cmdweakgroup "\\weakgroup".
357 \section cmddir \\dir [<path fragment>]
360 Indicates that a comment block contains documentation for a directory.
361 The "path fragment" argument should include the directory name and
362 enough of the path to be unique with respect to the other directories
364 The \ref cfg_strip_from_path "STRIP_FROM_PATH" option determines what is
365 stripped from the full path before it appears in the output.
368 \section cmdenum \\enum <name>
371 Indicates that a comment block contains documentation for an
372 enumeration, with name \<name\>. If the enum is a member of a class and
373 the documentation block is located outside the class definition,
374 the scope of the class should be specified as well.
375 If a comment block is located directly in front of an enum declaration,
376 the \c \\enum comment may be omitted.
379 The type of an anonymous enum cannot be documented, but the values
380 of an anonymous enum can.
385 Click <a href="$(DOXYGEN_DOCDIR)/examples/enum/html/class_test.html">here</a>
386 for the corresponding HTML documentation that is generated by doxygen.
390 \section cmdexample \\example <file-name>
393 Indicates that a comment block contains documentation for a source code
394 example. The name of the source file is \<file-name\>. The text of
395 this file will be included in the documentation, just after the
396 documentation contained in the comment block. All examples are placed
397 in a list. The source code is scanned for documented members and classes.
398 If any are found, the names are cross-referenced with the documentation.
399 Source files or directories can be specified using the
400 \ref cfg_example_path "EXAMPLE_PATH"
401 tag of doxygen's configuration file.
403 If \<file-name\> itself is not unique for the set of example files specified
405 \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part of the absolute path
408 If more than one source file is needed for the example,
409 the \ref cmdinclude "\\include" command can be used.
412 \verbinclude example.cpp
413 Where the example file \c example_test.cpp looks as follows:
414 \verbinclude example_test.cpp
416 Click <a href="$(DOXYGEN_DOCDIR)/examples/example/html/examples.html">here</a>
417 for the corresponding HTML documentation that is generated by doxygen.
420 \sa section \ref cmdinclude "\\include".
423 \section cmdendinternal \\endinternal
425 \addindex \\endinternal
426 This command ends a documentation fragment that was started with a
427 \ref cmdinternal "\\internal" command. The text between \ref cmdinternal "\\internal" and
428 \c \\endinternal will only be visible
429 if \ref cfg_internal_docs "INTERNAL_DOCS" is set to \c YES.
432 \section cmdextends \\extends <name>
435 This command can be used to manually indicate an inheritance relation,
436 when the programming language does not support this concept natively
439 The file \c manual.c in the example directory shows how to use this command.
442 Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a>
443 for the corresponding HTML documentation that is generated by doxygen.
446 \sa section \ref cmdimplements "\\implements" and section
447 \ref cmdmemberof "\\memberof"
450 \section cmdfile \\file [<name>]
453 Indicates that a comment block contains documentation for a source or
454 header file with name \<name\>. The file name may include (part of) the
455 path if the file-name alone is not unique. If the file name is omitted
456 (i.e. the line after \c \\file is left blank) then the documentation block that
457 contains the \c \\file command will belong to the file it is located in.
460 The documentation of global functions, variables, typedefs, and enums will
461 only be included in the output if the file they are in is documented as well.
466 Click <a href="$(DOXYGEN_DOCDIR)/examples/file/html/file_8h.html">here</a>
467 for the corresponding HTML documentation that is generated by doxygen.
470 \note In the above example \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF"
471 has been set to \c YES in the configuration file.
474 \section cmdfn \\fn (function declaration)
477 Indicates that a comment block contains documentation for a function
478 (either global or as a member of a class). This command is \em only
479 needed if a comment block is \e not placed in front (or behind)
480 the function declaration or definition.
482 If your comment block \e is in front of the function
483 declaration or definition this command can (and to avoid redundancy
486 A full function declaration including arguments should be specified after the
487 \c \\fn command on a \e single line, since the argument ends at the end
490 This command is equivalent to \ref cmdvar "\\var", \ref cmdtypedef "\\typedef",
491 and \ref cmdproperty "\\property".
493 \warning Do not use this command
494 if it is not absolutely needed, since it will lead to duplication of
495 information and thus to errors.
500 Click <a href="$(DOXYGEN_DOCDIR)/examples/func/html/class_test.html">here</a>
501 for the corresponding HTML documentation that is generated by doxygen.
505 \sa sections \ref cmdvar "\\var", \ref cmdproperty "\\property", and
506 \ref cmdtypedef "\\typedef".
509 \section cmdheaderfile \\headerfile <header-file> [<header-name>]
511 \addindex \\headerfile
512 Intended to be used for class, struct, or union documentation, where
513 the documentation is in front of the definition. The arguments of
514 this command are the same as the second and third argument of
515 \ref cmdclass "\\class".
516 The \<header-file\> name refers to the file that should be included by the
517 application to obtain the definition of the class, struct, or union.
518 The \<header-name\> argument can be used to overwrite the
519 name of the link that is used in the class documentation to something other
520 than \<header-file\>. This can be useful if the include name is not located
521 on the default include path (like \<X11/X.h\>).
523 With the \<header-name\>
524 argument you can also specify how the include statement should look like,
525 by adding either double quotes or sharp brackets around the name.
526 By default sharp brackets are used if just the name is given.
528 If a pair of double quotes is given for either the \<header-file\> or
529 \<header-name\> argument, the current file (in which the command was found)
530 will be used but with quotes. So for a comment block with a \c \\headerfile
531 command inside a file <code>test.h</code>, the following three commands are equivalent:
533 \headerfile test.h "test.h"
534 \headerfile test.h ""
535 \headerfile "" \endverbatim
536 To get sharp brackets you do not need to specify anything,
537 but if you want to be explicit you could use any of the following:
539 \headerfile test.h <test.h>
540 \headerfile test.h <>
541 \headerfile <> \endverbatim
543 To globally reverse the default include representation to
544 local includes you can set
545 \ref cfg_force_local_includes "FORCE_LOCAL_INCLUDES" to \c YES.
547 To disable the include information altogether set
548 \ref cfg_show_include_files "SHOW_INCLUDE_FILES" to \c NO.
551 \section cmdhideinitializer \\hideinitializer
553 \addindex \\hideinitializer
554 By default the value of a define and the initializer of a variable
555 are displayed unless they are longer than 30 lines. By putting
556 this command in a comment block of a define or variable, the
557 initializer is always hidden. The maximum number of initialization lines
558 can be changed by means of the configuration parameter
559 \ref cfg_max_initializer_lines "MAX_INITIALIZER_LINES", the default
562 \sa section \ref cmdshowinitializer "\\showinitializer".
565 \section cmdidlexcept \\idlexcept <name>
566 \addindex \\idlexcept
568 Indicates that a comment block contains documentation for a
569 IDL exception with name \<name\>.
572 \section cmdimplements \\implements <name>
574 \addindex \\implements
575 This command can be used to manually indicate an inheritance relation,
576 when the programming language does not support this concept natively
579 The file \c manual.c in the example directory shows how to use this command.
582 Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a>
583 for the corresponding HTML documentation that is generated by doxygen.
586 \sa section \ref cmdextends "\\extends" and section
587 \ref cmdmemberof "\\memberof"
590 \section cmdingroup \\ingroup (<groupname> [<groupname> <groupname>])
593 If the \c \\ingroup command is placed in a comment block of a
594 class, file or namespace, then it will be added to the group or
595 groups identified by \<groupname\>.
597 \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup",
598 \ref cmdaddtogroup "\\addtogroup", and \ref cmdweakgroup "\\weakgroup"
601 \section cmdinterface \\interface <name> [<header-file>] [<header-name>]
603 \addindex \\interface
604 Indicates that a comment block contains documentation for an
605 interface with name \<name\>. The arguments are equal to the arguments of the
606 \ref cmdclass "\\class" command.
608 \sa section \ref cmdclass "\\class".
611 \section cmdinternal \\internal
614 This command starts a documentation fragment that is meant for internal
615 use only. The fragment naturally ends at the end of the comment block.
616 You can also force the internal section to end earlier by using the
617 \ref cmdendinternal "\\endinternal" command.
619 If the \c \\internal command is put inside a section
620 (see for example \ref cmdsection "\\section") all subsections after the
621 command are considered to be internal as well. Only a new section at the
622 same level will end the fragment that is considered internal.
624 You can use \ref cfg_internal_docs "INTERNAL_DOCS" in the config file
625 to show (\c YES) or hide (\c NO) the internal documentation.
627 \sa section \ref cmdendinternal "\\endinternal".
631 \section cmdmainpage \\mainpage [(title)]
635 If the \c \\mainpage command is placed in a comment block the
636 block is used to customize the index page (in HTML) or
637 the first chapter (in \LaTeX).
639 The title argument is optional and replaces the default title that
640 doxygen normally generates. If you do not want any title you can
641 specify \c notitle as the argument of \c \\mainpage.
645 /*! \mainpage My Personal Index Page
647 * \section intro_sec Introduction
649 * This is the introduction.
651 * \section install_sec Installation
653 * \subsection step1 Step 1: Opening the box
659 You can refer to the main page using: <code>\ref cmdref "\\ref" index</code>.
661 \sa section \ref cmdsection "\\section",
662 section \ref cmdsubsection "\\subsection", and
663 section \ref cmdpage "\\page".
666 \section cmdmemberof \\memberof <name>
669 This command makes a function a member of a class in a similar way
670 as \ref cmdrelates "\\relates" does, only with this command the function
671 is represented as a real member of the class.
672 This can be useful when the programming language does not support
673 the concept of member functions natively (e.g. C).
675 It is also possible to use this command together with
676 \ref cmdpublic "\\public", \ref cmdprotected "\\protected" or
677 \ref cmdprivate "\\private".
679 The file \c manual.c in the example directory shows how to use this command.
682 Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a>
683 for the corresponding HTML documentation that is generated by doxygen.
686 \sa sections \ref cmdextends "\\extends", \ref cmdimplements "\\implements",
687 \ref cmdpublic "\\public", \ref cmdprotected "\\protected" and
688 \ref cmdprivate "\\private".
691 \section cmdname \\name [(header)]
695 This command turns a comment block into a header
696 definition of a member group. The
697 comment block should be followed by a
698 <code>//\@{ ... //\@}</code> block containing the
699 members of the group.
701 See section \ref memgroup for an example.
704 \section cmdnamespace \\namespace <name>
706 \addindex \\namespace
707 Indicates that a comment block contains documentation for a
708 namespace with name \<name\>.
711 \section cmdnosubgrouping \\nosubgrouping
713 \addindex \\nosubgrouping
714 This command can be put in the documentation
715 of a class. It can be used in combination with member grouping
716 to avoid that doxygen puts a member group as a subgroup of a
717 Public/Protected/Private/... section.
719 \sa sections \ref cmdpublicsection "\\publicsection",
720 \ref cmdprotectedsection "\\protectedsection" and
721 \ref cmdprivatesection "\\privatesection".
724 \section cmdoverload \\overload [(function declaration)]
727 This command can be used to generate the following
728 standard text for an overloaded member function:
730 > This is an overloaded member function, provided for convenience.
731 > It differs from the above function only in what argument(s) it accepts.
733 If the documentation for the overloaded member function is not located
734 in front of the function declaration or definition, the optional
735 argument should be used to specify the correct function.
737 Any other documentation that is inside the documentation block will
738 by appended after the generated message.
741 You are responsible that there is indeed an
742 earlier documented member that is overloaded by this one.
743 To prevent that document reorders the documentation you should set
744 \ref cfg_sort_member_docs "SORT_MEMBER_DOCS" to \c NO in this case.
746 The \c \\overload command does not work inside a one-line comment.
748 \verbinclude examples/overload.cpp
750 Click <a href="$(DOXYGEN_DOCDIR)/examples/overload/html/class_test.html">here</a>
751 for the corresponding HTML documentation that is generated by doxygen.
755 \section cmdpackage \\package <name>
758 Indicates that a comment block contains documentation for a
759 Java package with name \<name\>.
762 \section cmdpage \\page <name> (title)
765 Indicates that a comment block contains a piece of documentation that is
766 not directly related to one specific class, file or member.
767 The HTML generator creates a page containing the documentation. The
769 starts a new section in the chapter 'Page documentation'.
772 \verbinclude page.doc
774 Click <a href="$(DOXYGEN_DOCDIR)/examples/page/html/pages.html">here</a>
775 for the corresponding HTML documentation that is generated by doxygen.
779 The \<name\> argument consists of a combination of letters and number
780 digits. If you wish to use upper case letters (e.g. \c MYPAGE1), or
781 mixed case letters (e.g. \c MyPage1) in the \<name\> argument, you
782 should set \ref cfg_case_sense_names "CASE_SENSE_NAMES" to \c YES. However, this is advisable
783 only if your file system is case sensitive. Otherwise (and for better
784 portability) you should use all lower case letters (e.g. \c mypage1)
785 for \<name\> in all references to the page.
787 \sa section \ref cmdsection "\\section", section
788 \ref cmdsubsection "\\subsection", and section
792 \section cmdprivate \\private
795 Indicates that the member documented by the comment block is private,
796 i.e., should only be accessed by other members in the same class.
798 Note that Doxygen automatically detects the protection level of members
799 in object-oriented languages. This command is intended for use only when
800 the language does not support the concept of protection level natively
803 For starting a section of private members, in a way similar to the
804 "private:" class marker in C++, use \ref cmdprivatesection "\\privatesection".
806 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
807 \ref cmdprotected "\\protected" and \ref cmdprivatesection "\\privatesection".
810 \section cmdprivatesection \\privatesection
812 \addindex \\privatesection
813 Starting a section of private members, in a way similar to the
814 "private:" class marker in C++.
815 Indicates that the member documented by the comment block is private,
816 i.e., should only be accessed by other members in the same class.
818 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
819 \ref cmdprotected "\\protected" and \ref cmdprivate "\\private".
822 \section cmdproperty \\property (qualified property name)
825 Indicates that a comment block contains documentation for a
826 property (either global or as a member of a class).
827 This command is equivalent to \ref cmdfn "\\fn",
828 \ref cmdtypedef "\\typedef", and \ref cmdvar "\\var".
830 \sa sections \ref cmdfn "\\fn", \ref cmdtypedef "\\typedef", and
834 \section cmdprotected \\protected
836 \addindex \\protected
837 Indicates that the member documented by the comment block is protected,
838 i.e., should only be accessed by other members in the same or derived
841 Note that Doxygen automatically detects the protection level of members
842 in object-oriented languages. This command is intended for use only when
843 the language does not support the concept of protection level natively
846 For starting a section of protected members, in a way similar to the
847 "protected:" class marker in C++, use \ref cmdprotectedsection "\\protectedsection".
849 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
850 \ref cmdprivate "\\private" and \ref cmdprotectedsection "\\protectedsection".
853 \section cmdprotectedsection \\protectedsection
855 \addindex \\protectedsection
856 Starting a section of protected members, in a way similar to the
857 "protected:" class marker in C++.
858 Indicates that the member documented by the comment block is protected,
859 i.e., should only be accessed by other members in the same or derived
862 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
863 \ref cmdprivate "\\private" and \ref cmdprotected "\\protected".
866 \section cmdprotocol \\protocol <name> [<header-file>] [<header-name>]
869 Indicates that a comment block contains documentation for a
870 protocol in Objective-C with name \<name\>. The arguments are equal
871 to the \ref cmdclass "\\class" command.
873 \sa section \ref cmdclass "\\class".
876 \section cmdpublic \\public
879 Indicates that the member documented by the comment block is public,
880 i.e., can be accessed by any other class or function.
882 Note that Doxygen automatically detects the protection level of members
883 in object-oriented languages. This command is intended for use only when
884 the language does not support the concept of protection level natively
887 For starting a section of public members, in a way similar to the
888 "public:" class marker in C++, use \ref cmdpublicsection "\\publicsection".
890 \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected",
891 \ref cmdprivate "\\private" and \ref cmdpublicsection "\\publicsection".
894 \section cmdpublicsection \\publicsection
896 \addindex \\publicsection
897 Starting a section of public members, in a way similar to the
898 "public:" class marker in C++.
899 Indicates that the member documented by the comment block is public,
900 i.e., can be accessed by any other class or function.
902 \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected",
903 \ref cmdprivate "\\private" and \ref cmdpublic "\\public".
906 \section cmdpure \\pure
909 Indicates that the member documented by the comment block is pure virtual,
910 i.e., it is abstract and has no implementation associated with it.
912 This command is intended for use only when
913 the language does not support the concept of pure virtual methods natively
917 \section cmdrelates \\relates <name>
920 This command can be used in the documentation of a non-member function
921 \<name\>. It puts the function inside the 'related function' section
922 of the class documentation. This command is useful for documenting
923 non-friend functions that are nevertheless strongly coupled to a certain
924 class. It prevents the need of having to document a file, but
925 only works for functions.
928 \verbinclude relates.cpp
930 Click <a href="$(DOXYGEN_DOCDIR)/examples/relates/html/class_string.html">here</a>
931 for the corresponding HTML documentation that is generated by doxygen.
935 \section cmdrelated \\related <name>
938 Equivalent to \ref cmdrelates "\\relates"
941 \section cmdrelatesalso \\relatesalso <name>
943 \addindex \\relatesalso
944 This command can be used in the documentation of a non-member function
945 \<name\>. It puts the function both inside the 'related function' section
946 of the class documentation as well as leaving it at its normal file documentation
947 location. This command is useful for documenting
948 non-friend functions that are nevertheless strongly coupled to a certain
949 class. It only works for functions.
952 \section cmdrelatedalso \\relatedalso <name>
954 \addindex \\relatedalso
955 Equivalent to \ref cmdrelatesalso "\\relatesalso"
958 \section cmdshowinitializer \\showinitializer
960 \addindex \\showinitializer
961 By default the value of a define and the initializer of a variable
962 are only displayed if they are less than 30 lines long. By putting
963 this command in a comment block of a define or variable, the
964 initializer is shown unconditionally.
965 The maximum number of initialization lines
966 can be changed by means of the configuration parameter
967 \ref cfg_max_initializer_lines "MAX_INITIALIZER_LINES", the default value is
970 \sa section \ref cmdhideinitializer "\\hideinitializer".
973 \section cmdstatic \\static
976 Indicates that the member documented by the comment block is static,
977 i.e., it works on a class, instead of on an instance of the class.
979 This command is intended for use only when
980 the language does not support the concept of static methods natively (e.g. C).
983 \section cmdstruct \\struct <name> [<header-file>] [<header-name>]
986 Indicates that a comment block contains documentation for a
987 struct with name \<name\>. The arguments are equal to the arguments of the
988 \ref cmdclass "\\class" command.
990 \sa section \ref cmdclass "\\class".
993 \section cmdtypedef \\typedef (typedef declaration)
996 Indicates that a comment block contains documentation for a
997 typedef (either global or as a member of a class).
998 This command is equivalent to \ref cmdfn "\\fn",
999 \ref cmdproperty "\\property", and \ref cmdvar "\\var".
1001 \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and
1002 \ref cmdvar "\\var".
1005 \section cmdunion \\union <name> [<header-file>] [<header-name>]
1008 Indicates that a comment block contains documentation for a
1009 union with name \<name\>. The arguments are equal to the arguments of the
1010 \ref cmdclass "\\class" command.
1012 \sa section \ref cmdclass "\\class".
1015 \section cmdvar \\var (variable declaration)
1018 Indicates that a comment block contains documentation for a variable or
1019 enum value (either global or as a member of a class).
1020 This command is equivalent to \ref cmdfn "\\fn",
1021 \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef".
1023 \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef".
1026 \section cmdvhdlflow \\vhdlflow [(title for the flow chart)]
1028 \addindex \\vhdlflow
1029 This is a VHDL specific command, which can be put in the documentation of a process to
1030 produce a flow chart of the logic in the process.
1031 Optionally a title for the flow chart can be given.
1032 \note Currently the flow chart will only appear in the HTML output.
1035 \section cmdweakgroup \\weakgroup <name> [(title)]
1036 \addindex \\addtogroup
1037 Can be used exactly like \ref cmdaddtogroup "\\addtogroup", but has
1038 a lower priority when it comes to resolving conflicting grouping
1041 \sa page \ref grouping "Grouping" and section \ref cmdaddtogroup "\\addtogroup".
1045 \htmlonly <center> \endhtmlonly
1047 \htmlonly --- \endhtmlonly
1049 \htmlonly --- \endhtmlonly
1051 \htmlonly </center>\endhtmlonly
1054 \section cmdattention \\attention { attention text }
1056 \addindex \\attention
1057 Starts a paragraph where a message that needs attention may be entered.
1058 The paragraph will be indented.
1059 The text of the paragraph has no special internal structure. All visual
1060 enhancement commands may be used inside the paragraph.
1061 Multiple adjacent \c \\attention commands will be joined into a single paragraph.
1062 The \c \\attention command ends when a blank line or some other
1063 sectioning command is encountered.
1066 \section cmdauthor \\author { list of authors }
1069 Starts a paragraph where one or more author names may be entered.
1070 The paragraph will be indented.
1071 The text of the paragraph has no special internal structure. All visual
1072 enhancement commands may be used inside the paragraph.
1073 Multiple adjacent \c \\author commands will be joined into a single paragraph.
1074 Each author description will start a new line. Alternatively, one \c \\author command
1075 may mention several authors. The \c \\author command ends when a blank line or some other
1076 sectioning command is encountered.
1079 \verbinclude author.cpp
1081 Click <a href="$(DOXYGEN_DOCDIR)/examples/author/html/class_some_nice_class.html">here</a>
1082 for the corresponding HTML documentation that is generated by doxygen.
1086 \section cmdauthors \\authors { list of authors }
1089 Equivalent to \ref cmdauthor "\\author".
1092 \section cmdbrief \\brief { brief description }
1095 Starts a paragraph that serves as a brief description. For classes and files
1096 the brief description will be used in lists and at the start of the
1097 documentation page. For class and file members, the brief description
1098 will be placed at the declaration of the member and prepended to the
1099 detailed description. A brief description may span several lines (although
1100 it is advised to keep it brief!). A brief description ends when a
1101 blank line or another sectioning command is encountered. If multiple
1102 \c \\brief commands are present they will be joined. See section
1103 \ref cmdauthor "\\author" for an example.
1105 Synonymous to \ref cmdshort "\\short".
1108 \section cmdbug \\bug { bug description }
1111 Starts a paragraph where one or more bugs may be reported.
1112 The paragraph will be indented.
1113 The text of the paragraph has no special internal structure. All visual
1114 enhancement commands may be used inside the paragraph.
1115 Multiple adjacent \c \\bug commands will be joined into a single paragraph.
1116 Each bug description will start on a new line.
1117 Alternatively, one \c \\bug command may mention
1118 several bugs. The \c \\bug command ends when a blank line or some other
1119 sectioning command is encountered. See section \ref cmdauthor "\\author"
1123 \section cmdcond \\cond [(section-label)]
1126 Starts a conditional section that ends with a corresponding
1127 \ref cmdendcond "\\endcond" command, which is typically found in
1128 another comment block. The main purpose of this pair of
1129 commands is to (conditionally) exclude part of a file from processing
1130 (in older version of doxygen this could only be achieved using C preprocessor commands).
1132 The section between \c \\cond and \ref cmdendcond "\\endcond" can be included by
1133 adding its section label to the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1134 configuration option. If the section label is omitted, the section will
1135 be excluded from processing unconditionally. The section label can be a
1136 logical expression build of section labels, round brackets, && (AND), || (OR) and ! (NOT).
1137 If you use an expression you need to wrap it in round brackets, i.e
1138 <tt>\\cond (!LABEL1 && LABEL2)</tt>.
1140 For conditional sections within a comment block one should
1141 use a \ref cmdif "\\if" ... \ref cmdendif "\\endif" block.
1143 Conditional sections can be nested. In this case a nested section will only
1144 be shown if it and its containing section are included.
1146 Here is an example showing the commands in action:
1154 virtual void func() = 0;
1158 /** A method used for testing */
1159 virtual void test() = 0;
1166 * The implementation of the interface
1168 class Implementation : public Intf
1178 /** This method is obsolete and does
1179 * not show up in the documentation.
1188 The output will be different depending on whether or not \ref cfg_enabled_sections "ENABLED_SECTIONS"
1189 contains \c TEST, or \c DEV
1191 \sa sections \ref cmdendcond "\\endcond" and \ref cfg_enabled_sections "ENABLED_SECTIONS".
1194 \section cmdcopyright \\copyright { copyright description }
1196 \addindex \\copyright
1197 Starts a paragraph where the copyright of an entity can be described.
1198 This paragraph will be indented.
1199 The text of the paragraph has no special internal structure.
1200 See section \ref cmdauthor "\\author" for an example.
1203 \section cmddate \\date { date description }
1206 Starts a paragraph where one or more dates may be entered.
1207 The paragraph will be indented.
1208 The text of the paragraph has no special internal structure. All visual
1209 enhancement commands may be used inside the paragraph.
1210 Multiple adjacent \c \\date commands will be joined into a single paragraph.
1211 Each date description will start on a new line.
1212 Alternatively, one \c \\date command may mention
1213 several dates. The \c \\date command ends when a blank line or some other
1214 sectioning command is encountered. See section \ref cmdauthor "\\author"
1218 \section cmddeprecated \\deprecated { description }
1220 \addindex \\deprecated
1221 Starts a paragraph indicating that this documentation block belongs to
1222 a deprecated entity. Can be used to describe alternatives,
1223 expected life span, etc.
1226 \section cmddetails \\details { detailed description }
1229 Just like \ref cmdbrief "\\brief" starts a brief description, \c \\details
1230 starts the detailed description. You can also start a new paragraph (blank line)
1231 then the \c \\details command is not needed.
1234 \section cmdelse \\else
1237 Starts a conditional section if the previous conditional section
1238 was not enabled. The previous section should have been started with
1239 a \ref cmdif "\\if", \ref cmdifnot "\\ifnot", or \ref cmdelseif "\\elseif"
1242 \sa \ref cmdif "\\if", \ref cmdifnot "\\ifnot", \ref cmdelseif "\\elseif",
1243 \ref cmdendif "\\endif."
1246 \section cmdelseif \\elseif (section-label)
1249 Starts a conditional documentation section if the previous section
1250 was not enabled. A conditional section is
1251 disabled by default. To enable it you must put the
1252 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1253 tag in the configuration file. The section label can be a logical expression
1254 build of section names, round brackets, && (AND), || (OR) and ! (NOT).
1255 Conditional blocks can be nested. A nested section is
1256 only enabled if all enclosing sections are enabled as well.
1258 \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot",
1259 \ref cmdelse "\\else", and \ref cmdelseif "\\elseif".
1262 \section cmdendcond \\endcond
1265 Ends a conditional section that was started by \ref cmdcond "\\cond".
1267 \sa section \ref cmdcond "\\cond".
1270 \section cmdendif \\endif
1273 Ends a conditional section that was started by \ref cmdif "\\if" or \ref cmdifnot "\\ifnot"
1274 For each \ref cmdif "\\if" or \ref cmdifnot "\\ifnot" one and only one matching
1275 \ref cmdendif "\\endif" must follow.
1277 \sa sections \ref cmdif "\\if" and \ref cmdifnot "\\ifnot".
1280 \section cmdexception \\exception <exception-object> { exception description }
1282 \addindex \\exception
1283 Starts an exception description for an exception object with name
1284 \<exception-object\>. Followed by a description of the exception.
1285 The existence of the exception object is not checked.
1286 The text of the paragraph has no special internal structure. All visual
1287 enhancement commands may be used inside the paragraph.
1288 Multiple adjacent \c \\exception commands will be joined into a single paragraph.
1289 Each exception description will start on a new line.
1290 The \c \\exception description ends when a blank line or some other
1291 sectioning command is encountered. See section \ref cmdfn "\\fn" for an
1295 \section cmdif \\if (section-label)
1298 Starts a conditional documentation section. The section ends
1299 with a matching \ref cmdendif "\\endif" command. A conditional section is
1300 disabled by default. To enable it you must put the
1301 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1302 tag in the configuration file.
1304 The section label can be a logical expression
1305 build of section names, round brackets, && (AND), || (OR) and ! (NOT).
1306 If you use an expression you need to wrap it in round brackets, i.e
1307 <tt>\\cond (!LABEL1 && LABEL2)</tt>.
1309 Conditional blocks can be nested. A nested section is
1310 only enabled if all enclosing sections are enabled as well.
1314 /*! Unconditionally shown documentation.
1316 * Only included if Cond1 is set.
1319 * Only included if Cond2 is set.
1321 * Only included if Cond2 and Cond3 are set.
1325 * Unconditional text.
1329 You can also use conditional commands inside aliases. To
1330 document a class in two languages you could for instance use:
1338 * Dit is Nederlands.
1346 Where the following aliases are defined in the configuration file:
1349 ALIASES = "english=\if english" \
1350 "endenglish=\endif" \
1355 and \ref cfg_enabled_sections "ENABLED_SECTIONS" can be used to enable either \c english or \c dutch.
1357 \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot",
1358 \ref cmdelse "\\else", \ref cmdelseif "\\elseif", and
1359 \ref cfg_enabled_sections "ENABLED_SECTIONS".
1362 \section cmdifnot \\ifnot (section-label)
1365 Starts a conditional documentation section. The section ends
1366 with a matching \ref cmdendif "\\endif" command. This conditional section is
1367 enabled by default. To disable it you must put the
1368 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1369 tag in the configuration file. The section label can be a logical expression
1370 build of section names, round brackets, && (AND), || (OR) and ! (NOT).
1372 \sa sections \ref cmdendif "\\endif", \ref cmdif "\\if",
1373 \ref cmdelse "\\else", and \ref cmdelseif "\\elseif", and
1374 \ref cfg_enabled_sections "ENABLED_SECTIONS".
1377 \section cmdinvariant \\invariant { description of invariant }
1379 \addindex \\invariant
1380 Starts a paragraph where the invariant of an entity can be described.
1381 The paragraph will be indented.
1382 The text of the paragraph has no special internal structure. All visual
1383 enhancement commands may be used inside the paragraph.
1384 Multiple adjacent \c \\invariant commands will be joined into a single paragraph.
1385 Each invariant description will start on a new line.
1386 Alternatively, one \c \\invariant command may mention
1387 several invariants. The \c \\invariant command ends when a blank line or some other
1388 sectioning command is encountered.
1391 \section cmdnote \\note { text }
1394 Starts a paragraph where a note can be entered. The paragraph will be
1395 indented. The text of the paragraph has no special internal structure.
1396 All visual enhancement commands may be used inside the paragraph.
1397 Multiple adjacent \c \\note commands will be joined into a single paragraph.
1398 Each note description will start on a new line.
1399 Alternatively, one \c \\note command may mention
1400 several notes. The \c \\note command ends when a blank line or some other
1401 sectioning command is encountered. See section \ref cmdpar "\\par"
1405 \section cmdpar \\par [(paragraph title)] { paragraph }
1408 If a paragraph title is given this command starts a paragraph with a
1409 user defined heading. The heading extends until the end of the
1410 line. The paragraph following the command will be indented.
1412 If no paragraph title is given this command will start a new paragraph.
1413 This will also work inside other paragraph commands
1414 (like \ref cmdparam "\\param" or \ref cmdwarning "\\warning") without ending that command.
1416 The text of the paragraph has no special internal structure. All visual
1417 enhancement commands may be used inside the paragraph.
1418 The \c \\par command ends when a blank line or some other
1419 sectioning command is encountered.
1422 \verbinclude par.cpp
1424 Click <a href="$(DOXYGEN_DOCDIR)/examples/par/html/class_test.html">here</a>
1425 for the corresponding HTML documentation that is generated by doxygen.
1429 \section cmdparam \\param [(dir)] <parameter-name> { parameter description }
1432 Starts a parameter description for a function parameter with name
1433 \<parameter-name\>, followed by a description of the parameter.
1434 The existence of the parameter is checked and a warning is given if
1435 the documentation of this (or any other) parameter is missing or not
1436 present in the function declaration or definition.
1438 The \c \\param command has an optional attribute, (dir), specifying the direction
1439 of the parameter. Possible values are "[in]", "[in,out]", and "[out]",
1440 note the [square] brackets in this description.
1441 When a parameter is both input and output, [in,out] is used as attribute.
1442 Here is an example for the function \c memcpy:
1445 * Copies bytes from a source memory area to a destination memory area,
1446 * where both areas may not overlap.
1447 * @param[out] dest The memory area to copy to.
1448 * @param[in] src The memory area to copy from.
1449 * @param[in] n The number of bytes to copy
1451 void memcpy(void *dest, const void *src, size_t n);
1454 The parameter description is a paragraph with no special internal structure.
1455 All visual enhancement commands may be used inside the paragraph.
1457 Multiple adjacent \c \\param commands will be joined into a single paragraph.
1458 Each parameter description will start on a new line.
1459 The \c \\param description ends when a blank line or some other
1460 sectioning command is encountered. See section \ref cmdfn "\\fn" for an
1463 Note that you can also document multiple parameters with a single
1464 \c \\param command using a comma separated list. Here is an example:
1467 /** Sets the position.
1468 * @param x,y,z Coordinates of the position in 3D space.
1470 void setPosition(double x,double y,double z,double t)
1475 Note that for PHP one can also specify the type (or types if you
1476 separate them with a pipe symbol) which are allowed for a parameter
1477 (as this is not part of the definition).
1478 The syntax is the same as for phpDocumentor, i.e.
1480 @param datatype1|datatype2 $paramname description
1484 \section cmdparblock \\parblock
1485 \addindex \\parblock
1486 For commands that expect a single paragraph as argument
1487 (such as \ref cmdpar "\\par", \ref cmdparam "\\param" and \ref cmdwarning "\\warning"),
1488 the \ref cmdparblock "\\parblock" command allows to start a
1489 description that covers multiple paragraphs, which then ends with
1490 \ref cmdendparblock "\\endparblock".
1494 /** Example of a param command with a description consisting of two paragraphs
1497 * First paragraph of the param description.
1499 * Second paragraph of the param description.
1501 * Rest of the comment block continues.
1504 Note that the \c \\parblock command may also appear directly after
1505 \ref cmdparam "\\param"'s first argument.
1508 \section cmdendparblock \\endparblock
1509 \addindex \\endparblock
1510 This ends a block of paragraphs started with \ref cmdparblock "\\parblock".
1513 \section cmdtparam \\tparam <template-parameter-name> { description }
1516 Starts a template parameter for a class or function template parameter
1517 with name \<template-parameter-name\>, followed by a description of the
1520 Otherwise similar to \ref cmdparam "\\param".
1523 \section cmdpost \\post { description of the postcondition }
1526 Starts a paragraph where the postcondition of an entity can be described.
1527 The paragraph will be indented.
1528 The text of the paragraph has no special internal structure. All visual
1529 enhancement commands may be used inside the paragraph.
1530 Multiple adjacent \c \\post commands will be joined into a single paragraph.
1531 Each postcondition will start on a new line.
1532 Alternatively, one \c \\post command may mention
1533 several postconditions. The \c \\post command ends when a blank line or some other
1534 sectioning command is encountered.
1537 \section cmdpre \\pre { description of the precondition }
1540 Starts a paragraph where the precondition of an entity can be described.
1541 The paragraph will be indented.
1542 The text of the paragraph has no special internal structure. All visual
1543 enhancement commands may be used inside the paragraph.
1544 Multiple adjacent \c \\pre commands will be joined into a single paragraph.
1545 Each precondition will start on a new line.
1546 Alternatively, one \c \\pre command may mention
1547 several preconditions. The \c \\pre command ends when a blank line or some other
1548 sectioning command is encountered.
1551 \section cmdremark \\remark { remark text }
1554 Starts a paragraph where one or more remarks may be entered.
1555 The paragraph will be indented.
1556 The text of the paragraph has no special internal structure. All visual
1557 enhancement commands may be used inside the paragraph.
1558 Multiple adjacent \c \\remark commands will be joined into a single paragraph.
1559 Each remark will start on a new line.
1560 Alternatively, one \c \\remark command may mention
1561 several remarks. The \c \\remark command ends when a blank line or some other
1562 sectioning command is encountered.
1565 \section cmdremarks \\remarks { remark text }
1568 Equivalent to \ref cmdremark "\\remark".
1571 \section cmdresult \\result { description of the result value }
1574 Equivalent to \ref cmdreturn "\\return".
1577 \section cmdreturn \\return { description of the return value }
1580 Starts a return value description for a function.
1581 The text of the paragraph has no special internal structure. All visual
1582 enhancement commands may be used inside the paragraph.
1583 Multiple adjacent \c \\return commands will be joined into a single paragraph.
1584 The \c \\return description ends when a blank line or some other
1585 sectioning command is encountered. See section \ref cmdfn "\\fn" for an
1589 \section cmdreturns \\returns { description of the return value }
1592 Equivalent to \ref cmdreturn "\\return".
1595 \section cmdretval \\retval <return value> { description }
1598 Starts a description for a function's return value with name
1599 \<return value\>, followed by a description of the return value.
1600 The text of the paragraph that forms the description has no special
1601 internal structure. All visual enhancement commands may be used inside the
1603 Multiple adjacent \c \\retval commands will be joined into a single paragraph.
1604 Each return value description will start on a new line.
1605 The \c \\retval description ends when a blank line or some other
1606 sectioning command is encountered.
1609 \section cmdsa \\sa { references }
1612 Starts a paragraph where one or more cross-references to classes,
1613 functions, methods, variables, files or URL may be specified.
1614 Two names joined by either <code>::</code> or <code>\#</code>
1615 are understood as referring to a class and one of its members.
1616 One of several overloaded methods or constructors
1617 may be selected by including a parenthesized list of argument types after
1620 Synonymous to \ref cmdsee "\\see".
1622 \sa section \ref autolink "autolink" for information on how to create links
1626 \section cmdsee \\see { references }
1629 Equivalent to \ref cmdsa "\\sa". Introduced for compatibility with Javadoc.
1632 \section cmdshort \\short { short description }
1635 Equivalent to \ref cmdbrief "\\brief".
1638 \section cmdsince \\since { text }
1641 This command can be used to specify since when (version or time) an
1642 entity is available. The paragraph that follows \c \\since does not have any
1643 special internal structure. All visual enhancement commands may be
1644 used inside the paragraph. The \c \\since description ends when a blank
1645 line or some other sectioning command is encountered.
1648 \section cmdtest \\test { paragraph describing a test case }
1651 Starts a paragraph where a test case can be described.
1652 The description will also add the test case to a separate test list.
1653 The two instances of the description will be cross-referenced.
1654 Each test case in the test list will be preceded by a header that
1655 indicates the origin of the test case.
1658 \section cmdthrow \\throw <exception-object> { exception description }
1661 Synonymous \ref cmdexception "\\exception".
1664 the command \ref cmdthrows "\\throws" is a synonym for this command.
1666 \sa section \ref cmdexception "\\exception"
1669 \section cmdthrows \\throws <exception-object> { exception description }
1672 Equivalent to \ref cmdthrow "\\throw".
1675 \section cmdtodo \\todo { paragraph describing what is to be done }
1678 Starts a paragraph where a TODO item is described.
1679 The description will also add an item to a separate TODO list.
1680 The two instances of the description will be cross-referenced.
1681 Each item in the TODO list will be preceded by a header that
1682 indicates the origin of the item.
1685 \section cmdversion \\version { version number }
1688 Starts a paragraph where one or more version strings may be entered.
1689 The paragraph will be indented.
1690 The text of the paragraph has no special internal structure. All visual
1691 enhancement commands may be used inside the paragraph.
1692 Multiple adjacent \c \\version commands will be joined into a single paragraph.
1693 Each version description will start on a new line.
1694 Alternatively, one \c \\version command may mention
1695 several version strings.
1696 The \\version command ends when a blank line or some other
1697 sectioning command is encountered.
1698 See section \ref cmdauthor "\\author" for an example.
1701 \section cmdwarning \\warning { warning message }
1704 Starts a paragraph where one or more warning messages may be entered.
1705 The paragraph will be indented.
1706 The text of the paragraph has no special internal structure. All visual
1707 enhancement commands may be used inside the paragraph.
1708 Multiple adjacent \c \\warning commands will be joined into a single paragraph.
1709 Each warning description will start on a new line.
1710 Alternatively, one \c \\warning command may mention
1711 several warnings. The \c \\warning command ends when a blank line or some other
1712 sectioning command is encountered. See section \ref cmdauthor "\\author"
1716 \section cmdxrefitem \\xrefitem <key> "(heading)" "(list title)" { text }
1718 \addindex \\xrefitem
1719 This command is a generalization of commands such as \ref cmdtodo "\\todo"
1720 and \ref cmdbug "\\bug".
1721 It can be used to create user-defined text sections which are automatically
1722 cross-referenced between the place of occurrence and a related page,
1723 which will be generated. On the related page all sections of
1724 the same type will be collected.
1726 The first argument \<key\> is an
1727 identifier uniquely representing the type of the section. The second argument
1728 is a quoted string representing the heading of the section under which
1729 text passed as the fourth argument is put. The third argument (list title)
1730 is used as the title for the related page containing all items with the
1731 same key. The keys \c "todo", \c "test", \c "bug" and \c "deprecated" are predefined.
1733 To get an idea on how to use the \c \\xrefitem command and what its effect
1734 is, consider the todo list, which (for English output) can be seen an
1735 alias for the command
1736 \verbatim \xrefitem todo "Todo" "Todo List" \endverbatim
1738 Since it is very tedious and error-prone to repeat the first three
1739 parameters of the command for each section, the command is meant to
1740 be used in combination with the \ref cfg_aliases "ALIASES" option in the
1742 To define a new command \c \\reminder, for instance, one should add the following
1743 line to the configuration file:
1744 \verbatim ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" \endverbatim
1745 Note the use of escaped quotes for the second and third argument of the
1746 \c \\xrefitem command.
1748 In case parameter "(heading)" is the empty string no heading is generated. This can be useful
1749 when used in combination with the \ref cmdpage "\\page" command e.g.
1751 /** @page my_errors My Errors
1752 * @brief Errors page
1754 * Errors page contents.
1757 /** \error ERROR 101: in case a file can not be opened.
1758 Check about file system read/write access. */
1759 #define MY_ERR_CANNOT_OPEN_FILE 101
1761 /** \error ERROR 102: in case a file can not be closed.
1762 Check about file system read/write access. */
1763 #define MY_ERR_CANNOT_CLOSE_FILE 102
1765 with \c \\error defined as
1766 \verbatim ALIASES += "error=\xrefitem my_errors \"\" \"\"" \endverbatim
1770 \htmlonly <center> \endhtmlonly
1772 \htmlonly --- \endhtmlonly
1773 Commands to create links
1774 \htmlonly --- \endhtmlonly
1776 \htmlonly </center>\endhtmlonly
1779 \section cmdaddindex \\addindex (text)
1781 \addindex \\addindex
1782 This command adds (text) to the \LaTeX index.
1785 \section cmdanchor \\anchor <word>
1788 This command places an invisible, named anchor into the documentation
1789 to which you can refer with the \ref cmdref "\\ref" command.
1791 \note Anchors can currently only be put into a comment block
1792 that is marked as a page (using \ref cmdpage "\\page") or mainpage
1793 (\ref cmdmainpage "\\mainpage").
1795 \sa section \ref cmdref "\\ref".
1798 \section cmdcite \\cite <label>
1801 Adds a bibliographic reference in the text and in the list of bibliographic
1802 references. The \<label\> must be a valid BibTeX label that can be found
1803 in one of the .bib files listed in \ref cfg_cite_bib_files "CITE_BIB_FILES".
1804 For the \LaTeX output the formatting of the reference in the text can be
1805 configured with \ref cfg_latex_bib_style "LATEX_BIB_STYLE". For other
1806 output formats a fixed representation is used. Note that using this
1807 command requires the \c bibtex tool to be present in the search path.
1810 \section cmdendlink \\endlink
1813 This command ends a link that is started with the \ref cmdlink "\\link" command.
1815 \sa section \ref cmdlink "\\link".
1818 \section cmdlink \\link <link-object>
1821 The links that are automatically generated by doxygen always have the
1822 name of the object they point to as link-text.
1824 The \c \\link command can be used to create a link to an object (a file,
1825 class, or member) with a user specified link-text.
1826 The link command should end with an \ref cmdendlink "\\endlink" command. All text between
1827 the \c \\link and \ref cmdendlink "\\endlink" commands serves as text for a link to
1828 the \<link-object\> specified as the first argument of \c \\link.
1830 \sa Section \ref autolink "autolink" for more information on automatically
1831 generated links and valid link-objects.
1834 \section cmdref \\ref <name> ["(text)"]
1837 Creates a reference to a named section, subsection, page or anchor.
1838 For HTML documentation the reference command will generate a link to
1839 the section. For a section or subsection the title of the section will be
1840 used as the text of the link. For an anchor the optional text between quotes
1841 will be used or \<name\> if no text is specified.
1842 For \LaTeX documentation the reference command will
1843 generate a section number for sections or the text followed by a
1844 page number if \<name\> refers to an anchor.
1847 Section \ref cmdpage "\\page" for an example of the \c \\ref command.
1850 \section cmdrefitem \\refitem <name>
1852 Just like the \ref cmdref "\\ref" command, this command creates a reference
1853 to a named section, but this reference appears in a list that is started by
1854 \ref cmdsecreflist "\\secreflist"
1855 and ends with \ref cmdendsecreflist "\\endsecreflist".
1856 An example of such a list can be seen
1857 \ref showsecreflist "at the top of the page".
1860 \section cmdsecreflist \\secreflist
1861 \addindex \\secreflist
1862 Starts an index list of item, created with \ref cmdrefitem "\\refitem"
1863 that each link to a named section.
1866 \section cmdendsecreflist \\endsecreflist
1867 \addindex \\endsecreflist
1868 End an index list started with \ref cmdsecreflist "\\secreflist".
1871 \section cmdsubpage \\subpage <name> ["(text)"]
1874 This command can be used to create a hierarchy of pages. The
1875 same structure can be made using the \ref cmddefgroup "\\defgroup" and
1876 \ref cmdingroup "\\ingroup" commands, but for pages the \c \\subpage command
1877 is often more convenient. The main page (see \ref cmdmainpage "\\mainpage")
1878 is typically the root of hierarchy.
1880 This command behaves similar as \ref cmdref "\\ref" in the sense that
1881 it creates a reference to a page labeled \<name\> with the optional
1882 link text as specified in the second argument.
1884 It differs from the \ref cmdref "\\ref" command in that it only works for pages,
1885 and creates a parent-child relation between pages, where the
1886 child page (or sub page) is identified by label \<name\>.
1888 See the \ref cmdsection "\\section"
1889 and \ref cmdsubsection "\\subsection" commands if you want to add structure
1890 without creating multiple pages.
1892 \note Each page can be the sub page of only one other page and
1893 no cyclic relations are allowed, i.e. the page hierarchy must have a tree
1898 /*! \mainpage A simple manual
1902 This manual is divided in the following sections:
1904 - \subpage advanced "Advanced usage"
1907 //-----------------------------------------------------------
1909 /*! \page intro Introduction
1910 This page introduces the user to the topic.
1911 Now you can proceed to the \ref advanced "advanced section".
1914 //-----------------------------------------------------------
1916 /*! \page advanced Advanced Usage
1917 This page is for advanced users.
1918 Make sure you have first read \ref intro "the introduction".
1923 \section cmdtableofcontents \\tableofcontents
1925 \addindex \\tableofcontents
1926 Creates a table of contents at the top of a page, listing all
1927 sections and subsections in the page.
1929 \warning This command only works inside related page documentation and
1930 \e not in other documentation blocks and only has effect in the
1934 \section cmdsection \\section <section-name> (section title)
1937 Creates a section with name \<section-name\>. The title of the
1938 section should be specified as the second argument of the \c \\section
1941 \warning This command only works inside related page documentation and
1942 \e not in other documentation blocks!
1945 Section \ref cmdpage "\\page" for an example of the
1946 \c \\section command.
1949 \section cmdsubsection \\subsection <subsection-name> (subsection title)
1951 \addindex \\subsection
1952 Creates a subsection with name \<subsection-name\>. The title of the
1953 subsection should be specified as the second argument of the \c \\subsection
1956 \warning This command only works inside a section of a related page
1957 documentation block and
1958 \e not in other documentation blocks!
1961 Section \ref cmdpage "\\page" for an example of the
1962 \c \\subsection command.
1965 \section cmdsubsubsection \\subsubsection <subsubsection-name> (subsubsection title)
1967 \addindex \\subsubsection
1968 Creates a subsubsection with name \<subsubsection-name\>. The title of the
1969 subsubsection should be specified as the second argument of the
1970 \c \\subsubsection command.
1972 \warning This command only works inside a subsection of a
1973 related page documentation block and
1974 \e not in other documentation blocks!
1977 Section \ref cmdpage "\\page" for an example of the
1978 \ref cmdsection "\\section" command and
1979 \ref cmdsubsection "\\subsection" command.
1982 \section cmdparagraph \\paragraph <paragraph-name> (paragraph title)
1984 \addindex \\paragraph
1985 Creates a named paragraph with name \<paragraph-name\>. The title of the
1986 paragraph should be specified as the second argument of the
1987 \c \\paragraph command.
1989 \warning This command only works inside a subsubsection of a
1990 related page documentation block and
1991 \e not in other documentation blocks!
1995 \htmlonly <center> \endhtmlonly
1997 \htmlonly --- \endhtmlonly
1998 Commands for displaying examples
1999 \htmlonly --- \endhtmlonly
2001 \htmlonly </center>\endhtmlonly
2004 \section cmddontinclude \\dontinclude <file-name>
2006 \addindex \\dontinclude
2007 This command can be used to parse a source file without actually
2008 verbatim including it in the documentation (as the \ref cmdinclude "\\include" command does).
2009 This is useful if you want to divide the source file into smaller pieces and
2010 add documentation between the pieces.
2011 Source files or directories can be specified using the
2012 \ref cfg_example_path "EXAMPLE_PATH"
2013 tag of doxygen's configuration file.
2015 The class and member declarations and definitions inside the code fragment
2016 are 'remembered' during the parsing of the comment block that contained
2017 the \c \\dontinclude command.
2019 For line by line descriptions of source files, one or more lines
2020 of the example can be displayed using the \ref cmdline "\\line",
2021 \ref cmdskip "\\skip", \ref cmdskipline "\\skipline", and
2022 \ref cmduntil "\\until" commands. An internal pointer is used for these commands. The
2023 \c \\dontinclude command sets the pointer to the first line of the example.
2026 \verbinclude include.cpp
2027 Where the example file \c example_test.cpp looks as follows:
2028 \verbinclude example_test.cpp
2030 Click <a href="$(DOXYGEN_DOCDIR)/examples/include/html/example.html">here</a>
2031 for the corresponding HTML documentation that is generated by doxygen.
2034 Alternatively, the \ref cmdsnippet "\\snippet" command can be used to
2035 include only a fragment of a source file. For this to work the
2036 fragment has to be marked.
2038 \sa sections \ref cmdline "\\line", \ref cmdskip "\\skip",
2039 \ref cmdskipline "\\skipline", \ref cmduntil "\\until", and
2040 \ref cmdinclude "\\include".
2043 \section cmdinclude \\include <file-name>
2046 This command can be used to include a source file as a block of code.
2047 The command takes the name of an include file as an argument.
2048 Source files or directories can be specified using the
2049 \ref cfg_example_path "EXAMPLE_PATH"
2050 tag of doxygen's configuration file.
2052 If \<file-name\> itself is not unique for the set of example files specified
2053 by the \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part
2054 of the absolute path to disambiguate it.
2056 Using the \c \\include command is equivalent to inserting the file into
2057 the documentation block and surrounding it
2058 with \ref cmdcode "\\code" and \ref cmdendcode "\\endcode" commands.
2060 The main purpose of the \c \\include command is to avoid code
2061 duplication in case of example blocks that consist of multiple
2062 source and header files.
2064 For a line by line description of a source files use the
2065 \ref cmddontinclude "\\dontinclude" command in combination with
2066 the \ref cmdline "\\line", \ref cmdskip "\\skip",
2067 \ref cmdskipline "\\skipline",
2068 and \ref cmduntil "\\until" commands.
2070 Alternatively, the \ref cmdsnippet "\\snippet" command can be used to
2071 include only a fragment of a source file. For this to work the
2072 fragment has to be marked.
2074 \note Doxygen's special commands do not work inside blocks of code.
2075 It is allowed to nest C-style comments inside a code block though.
2077 \sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude", and
2078 \ref cmdverbatim "\\verbatim".
2081 \section cmdincludelineno \\includelineno <file-name>
2083 \addindex \\includelineno
2084 This command works the same way as \ref cmdinclude "\\include", but will add line
2085 numbers to the included file.
2087 \sa section \ref cmdinclude "\\include".
2090 \section cmdline \\line ( pattern )
2093 This command searches line by line through the example that was last
2094 included using \ref cmdinclude "\\include" or
2095 \ref cmddontinclude "\\dontinclude" until it finds a non-blank
2096 line. If that line contains the specified pattern, it is written
2099 The internal pointer that is used to keep track of the current line in
2100 the example, is set to the start of the line following the non-blank
2101 line that was found (or to the end of the example if no such line could
2104 See section \ref cmddontinclude "\\dontinclude" for an example.
2107 \section cmdskip \\skip ( pattern )
2110 This command searches line by line through the example that was last
2111 included using \ref cmdinclude "\\include" or
2112 \ref cmddontinclude "\\dontinclude" until it finds a line that contains
2113 the specified pattern.
2115 The internal pointer that is used to keep track of the current line in
2116 the example, is set to the start of the line that contains the specified
2117 pattern (or to the end of the example if the pattern could not be found).
2119 See section \ref cmddontinclude "\\dontinclude" for an example.
2122 \section cmdskipline \\skipline ( pattern )
2124 \addindex \\skipline
2125 This command searches line by line through the example that was last
2126 included using \ref cmdinclude "\\include" or
2127 \ref cmddontinclude "\\dontinclude" until it finds a line that contains
2128 the specified pattern. It then writes the line to the output.
2130 The internal pointer that is used to keep track of the current line in
2131 the example, is set to the start of the line following the line that is
2132 written (or to the end of the example if the pattern could not be found).
2136 \verbatim\skipline pattern\endverbatim
2140 \line pattern\endverbatim
2142 See section \ref cmddontinclude "\\dontinclude" for an example.
2145 \section cmdsnippet \\snippet <file-name> ( block_id )
2148 Where the \ref cmdinclude "\\include" command can be used to include
2149 a complete file as source code, this command can be used to quote only
2150 a fragment of a source file.
2152 For example, the putting the following command in the documentation,
2153 references a snippet in file \c example.cpp residing in a subdirectory
2154 which should be pointed to by \ref cfg_example_path "EXAMPLE_PATH".
2157 \snippet snippets/example.cpp Adding a resource
2160 The text following the file name is the unique identifier for the snippet.
2161 This is used to delimit the quoted code in the relevant snippet file as
2162 shown in the following example that corresponds to the above \c \\snippet
2166 QImage image(64, 64, QImage::Format_RGB32);
2167 image.fill(qRgb(255, 160, 128));
2169 //! [Adding a resource]
2170 document->addResource(QTextDocument::ImageResource,
2171 QUrl("mydata://image.png"), QVariant(image));
2172 //! [Adding a resource]
2176 Note that the lines containing the block markers will not be included,
2177 so the output will be:
2180 document->addResource(QTextDocument::ImageResource,
2181 QUrl("mydata://image.png"), QVariant(image));
2184 Note also that the [block_id] markers should appear exactly twice in the
2187 see section \ref cmddontinclude "\\dontinclude" for an alternative way
2188 to include fragments of a source file that does not require markers.
2191 \section cmduntil \\until ( pattern )
2194 This command writes all lines of the example that was last
2195 included using \ref cmdinclude "\\include" or
2196 \ref cmddontinclude "\\dontinclude" to the output, until it finds
2197 a line containing the specified pattern. The line containing the pattern
2198 will be written as well.
2200 The internal pointer that is used to keep track of the current line in
2201 the example, is set to the start of the line following last written
2202 line (or to the end of the example if the pattern could not be found).
2204 See section \ref cmddontinclude "\\dontinclude" for an example.
2207 \section cmdverbinclude \\verbinclude <file-name>
2209 \addindex \\verbinclude
2210 This command includes the file \<file-name\> verbatim in the documentation.
2211 The command is equivalent to pasting the file in the documentation and
2212 placing \ref cmdverbatim "\\verbatim" and \ref cmdendverbatim "\\endverbatim"
2215 Files or directories that doxygen should look for can be specified using the
2216 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
2219 \section cmdhtmlinclude \\htmlinclude <file-name>
2221 \addindex \\htmlinclude
2222 This command includes the file \<file-name\> as is in the HTML documentation.
2223 The command is equivalent to pasting the file in the documentation and
2224 placing \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly"
2227 Files or directories that doxygen should look for can be specified using the
2228 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
2232 \section cmdlatexinclude \\latexinclude <file-name>
2234 \addindex \\latexinclude
2235 This command includes the file \<file-name\> as is in the \LaTeX documentation.
2236 The command is equivalent to pasting the file in the documentation and
2237 placing \ref cmdlatexonly "\\latexonly" and \ref cmdendlatexonly "\\endlatexonly"
2240 Files or directories that doxygen should look for can be specified using the
2241 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
2245 \htmlonly <center> \endhtmlonly
2247 \htmlonly --- \endhtmlonly
2248 Commands for visual enhancements
2249 \htmlonly --- \endhtmlonly
2251 \htmlonly </center>\endhtmlonly
2253 \section cmda \\a <word>
2256 Displays the argument \<word\> in italics.
2257 Use this command to emphasize words.
2258 Use this command to refer to member arguments in the running text.
2262 ... the \a x and \a y coordinates are used to ...
2264 This will result in the following text:<br><br>
2265 ... the \a x and \a y coordinates are used to ...
2267 Equivalent to \ref cmde "\\e" and \ref cmdem "\\em".
2268 To emphasize multiple words use \<em\>multiple words\</em\>.
2271 \section cmdarg \\arg { item-description }
2274 This command has one argument that continues until the first
2275 blank line or until another \c \\arg is encountered.
2276 The command can be used to generate a simple, not nested list of
2278 Each argument should start with a \c \\arg command.
2283 \arg \c AlignLeft left alignment.
2284 \arg \c AlignCenter center alignment.
2285 \arg \c AlignRight right alignment
2287 No other types of alignment are supported.
2289 will result in the following text:<br><br>
2291 <li> \c AlignLeft left alignment.
2292 <li> \c AlignCenter center alignment.
2293 <li> \c AlignRight right alignment
2295 No other types of alignment are supported.
2298 For nested lists, HTML commands should be used.
2300 Equivalent to \ref cmdli "\\li"
2304 \section cmdb \\b <word>
2307 Displays the argument \<word\> using a bold font.
2308 Equivalent to \<b\>word\</b\>.
2309 To put multiple words in bold use \<b\>multiple words\</b\>.
2312 \section cmdc \\c <word>
2315 Displays the argument \<word\> using a typewriter font.
2316 Use this to refer to a word of code.
2317 Equivalent to \<tt\>word\</tt\>.
2322 ... This function returns \c void and not \c int ...
2324 will result in the following text:<br><br>
2325 ... This function returns \c void and not \c int ...
2327 Equivalent to \ref cmdp "\\p"
2328 To have multiple words in typewriter font use \<tt\>multiple words\</tt\>.
2331 \section cmdcode \\code [ '{'<word>'}']
2334 Starts a block of code. A code block is treated differently
2335 from ordinary text. It is interpreted as source code. The names of
2336 classes and members and other documented entities are automatically
2337 replaced by links to the documentation.
2339 By default the language that is assumed for syntax highlighting is based
2340 on the location where the \c \\code block was found. If this part of
2341 a Python file for instance, the syntax highlight will be done according
2342 to the Python syntax.
2344 If it unclear from the context which language is meant (for instance the
2345 comment is in a <code>.txt</code> or <code>.markdown</code> file) then you can also explicitly
2346 indicate the language, by putting the file extension typically
2347 that doxygen associated with the language in curly brackets after the
2348 code block. Here is an example:
2361 If the contents of the code block are in a language that doxygen cannot parse, doxygen
2362 will just show the output as-is. You can make this explicit using .unparsed, or by
2363 giving some other extension that doxygen doesn't support, e.g.
2367 Show this as-is please
2371 echo "This is a shell script"
2375 \sa section \ref cmdendcode "\\endcode" and section \ref cmdverbatim "\\verbatim".
2378 \section cmdcopydoc \\copydoc <link-object>
2381 Copies a documentation block from the object specified by \<link-object\>
2382 and pastes it at the location of the command. This command can be useful
2383 to avoid cases where a documentation block would otherwise have to be
2384 duplicated or it can be used to extend the documentation of an inherited
2387 The link object can point to a member (of a class, file or group),
2388 a class, a namespace, a group, a page, or a file (checked in that order).
2389 Note that if the object pointed to is a member (function, variable,
2390 typedef, etc), the compound (class, file, or group) containing it
2391 should also be documented for the copying to work.
2393 To copy the documentation for a member of a
2394 class one can, for instance, put the following in the documentation:
2397 /*! @copydoc MyClass::myfunction()
2398 * More documentation.
2402 if the member is overloaded, you should specify the argument types
2403 explicitly (without spaces!), like in the following:
2406 //! @copydoc MyClass::myfunction(type1,type2)
2409 Qualified names are only needed if the context in which the documentation
2410 block is found requires them.
2412 The \c \\copydoc command can be used recursively, but cycles in the \c \\copydoc
2413 relation will be broken and flagged as an error.
2415 Note that <code>\\copydoc foo()</code> is roughly equivalent to doing:
2417 \brief \copybrief foo()
2418 \details \copydetails foo()
2420 See \ref cmdcopybrief "\\copybrief" and
2421 \ref cmdcopydetails "\\copydetails" for copying only the brief or
2422 detailed part of the comment block.
2425 \section cmdcopybrief \\copybrief <link-object>
2427 \addindex \\copybrief
2428 Works in a similar way as \ref cmdcopydoc "\\copydoc" but will
2429 only copy the brief description, not the detailed documentation.
2432 \section cmdcopydetails \\copydetails <link-object>
2434 \addindex \\copydetails
2435 Works in a similar way as \ref cmdcopydoc "\\copydoc" but will
2436 only copy the detailed documentation, not the brief description.
2439 \section cmddocbookonly \\docbookonly
2441 \addindex \\docbookonly
2442 Starts a block of text that will be verbatim included in the
2443 generated docbook documentation only. The block ends with a
2444 \ref cmdenddocbookonly "\\enddocbookonly" command.
2446 \sa section \ref cmdmanonly "\\manonly",
2447 \ref cmdlatexonly "\\latexonly",
2448 \ref cmdrtfonly "\\rtfonly",
2449 \ref cmdxmlonly "\\xmlonly", and
2450 \ref cmdhtmlonly "\\htmlonly".
2453 \section cmddot \\dot
2456 Starts a text fragment which should contain a valid description of a
2457 dot graph. The text fragment ends with \ref cmdenddot "\\enddot".
2458 Doxygen will pass the text on to dot and include the resulting
2459 image (and image map) into the output.
2460 The nodes of a graph can be made clickable by using the URL attribute.
2461 By using the command \ref cmdref "\\ref" inside the URL value you can conveniently
2462 link to an item inside doxygen. Here is an example:
2472 * Class relations expressed via an inline dot graph:
2475 * node [shape=record, fontname=Helvetica, fontsize=10];
2476 * b [ label="class B" URL="\ref B"];
2477 * c [ label="class C" URL="\ref C"];
2478 * b -> c [ arrowhead="open", style="dashed" ];
2481 * Note that the classes in the above graph are clickable
2482 * (in the HTML output).
2487 \section cmdmsc \\msc
2490 Starts a text fragment which should contain a valid description of a
2491 message sequence chart. See http://www.mcternan.me.uk/mscgen/ for examples.
2492 The text fragment ends with \ref cmdendmsc "\\endmsc".
2493 \note The text fragment should only include the part of the message
2494 sequence chart that is
2495 within the <code>msc {...}</code> block.
2496 \note You need to install the <code>mscgen</code> tool, if you want to use this
2499 Here is an example of the use of the \c \\msc command.
2501 /** Sender class. Can be used to send a command to the server.
2502 * The receiver will acknowledge the command by calling Ack().
2505 * Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"];
2506 * Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"];
2512 /** Acknowledgment from server */
2516 /** Receiver class. Can be used to receive and execute commands.
2517 * After execution of a command, the receiver will send an acknowledgment
2520 * Receiver<-Sender [label="Command()", URL="\ref Command()"];
2521 * Receiver->Sender [label="Ack()", URL="\ref Sender::Ack()", ID="1"];
2527 /** Executable a command on the server */
2528 void Command(int commandId);
2533 \sa section \ref cmdmscfile "\\mscfile".
2536 \section cmdstartuml \\startuml
2538 \addindex \\startuml
2539 Starts a text fragment which should contain a valid description of a
2540 PlantUML diagram. See http://plantuml.sourceforge.net/ for examples.
2541 The text fragment ends with \ref cmdenduml "\\enduml".
2542 \note You need to install Java and the PlantUML's jar file,
2543 if you want to use this command. The location of the jar file should be specified
2544 using \ref cfg_plantuml_jar_path "PLANTUML_JAR_PATH".
2546 Here is an example of the use of the \c \\startuml command.
2548 /** Sender class. Can be used to send a command to the server.
2549 * The receiver will acknowledge the command by calling Ack().
2551 * Sender->Receiver : Command()
2552 * Sender<--Receiver : Ack()
2558 /** Acknowledgment from server */
2562 /** Receiver class. Can be used to receive and execute commands.
2563 * After execution of a command, the receiver will send an acknowledgment
2565 * Receiver<-Sender : Command()
2566 * Receiver-->Sender : Ack()
2572 /** Executable a command on the server */
2573 void Command(int commandId);
2577 \note For compatibility with running PlantUML as a preprocessing step before
2578 running doxygen, you can also add the name of the image file after \c \\startuml
2579 and inside curly brackets, i.e.
2581 @startuml{myimage.png}
2582 Alice -> Bob : Hello
2585 When the name of the image is specified, doxygen will generate an image with that name.
2586 Without the name doxygen will choose a name automatically.
2589 \section cmddotfile \\dotfile <file> ["caption"]
2592 Inserts an image generated by dot from \<file\> into the documentation.
2594 The first argument specifies the file name of the image.
2595 doxygen will look for files in the paths (or files) that you specified
2596 after the \ref cfg_dotfile_dirs "DOTFILE_DIRS" tag.
2597 If the dot file is found it will be used as an input file to the dot tool.
2598 The resulting image will be put into the correct output directory.
2599 If the dot file name contains spaces you'll have to put quotes ("...") around it.
2601 The second argument is optional and can be used to specify the caption
2602 that is displayed below the image. This argument has to be specified
2603 between quotes even if it does not contain any spaces. The quotes are
2604 stripped before the caption is displayed.
2607 \section cmdmscfile \\mscfile <file> ["caption"]
2610 Inserts an image generated by mscgen from \<file\> into the documentation.
2611 See http://www.mcternan.me.uk/mscgen/ for examples.
2613 The first argument specifies the file name of the image.
2614 doxygen will look for files in the paths (or files) that you specified
2615 after the \ref cfg_mscfile_dirs "MSCFILE_DIRS" tag.
2616 If the msc file is found it will be used as an input file to the mscgen tool.
2617 The resulting image will be put into the correct output directory.
2618 If the msc file name contains spaces you'll have to put quotes ("...") around it.
2620 The second argument is optional and can be used to specify the caption
2621 that is displayed below the image. This argument has to be specified
2622 between quotes even if it does not contain any spaces. The quotes are
2623 stripped before the caption is displayed.
2625 \sa section \ref cmdmsc "\\msc".
2628 \section cmddiafile \\diafile <file> ["caption"]
2631 Inserts an image made in dia from \<file\> into the documentation.
2633 The first argument specifies the file name of the image.
2634 doxygen will look for files in the paths (or files) that you specified
2635 after the \ref cfg_diafile_dirs "DIAFILE_DIRS" tag.
2636 If the dia file is found it will be used as an input file dia.
2637 The resulting image will be put into the correct output directory.
2638 If the dia file name contains spaces you'll have to put quotes ("...") around it.
2640 The second argument is optional and can be used to specify the caption
2641 that is displayed below the image. This argument has to be specified
2642 between quotes even if it does not contain any spaces. The quotes are
2643 stripped before the caption is displayed.
2646 \section cmde \\e <word>
2649 Displays the argument \<word\> in italics.
2650 Use this command to emphasize words.
2655 ... this is a \e really good example ...
2657 will result in the following text:<br><br>
2658 ... this is a \e really good example ...
2660 Equivalent to \ref cmda "\\a" and \ref cmdem "\\em".
2661 To emphasize multiple words use \<em\>multiple words\</em\>.
2664 \section cmdem \\em <word>
2667 Displays the argument \<word\> in italics.
2668 Use this command to emphasize words.
2673 ... this is a \em really good example ...
2675 will result in the following text:<br><br>
2676 ... this is a \em really good example ...
2678 Equivalent to \ref cmda "\\a" and \ref cmde "\\e".
2679 To emphasize multiple words use \<em\>multiple words\</em\>.
2682 \section cmdendcode \\endcode
2685 Ends a block of code.
2686 \sa section \ref cmdcode "\\code"
2689 \section cmdenddocbookonly \\enddocbookonly
2691 \addindex \\enddocbookonly
2692 Ends a block of text that was started with a \ref cmddocbookonly "\\docbookonly" command.
2694 \sa section \ref cmddocbookonly "\\docbookonly".
2697 \section cmdenddot \\enddot
2700 Ends a block that was started with \ref cmddot "\\dot".
2703 \section cmdendmsc \\endmsc
2706 Ends a block that was started with \ref cmdmsc "\\msc".
2709 \section cmdenduml \\enduml
2712 Ends a block that was started with \ref cmdstartuml "\\startuml".
2715 \section cmdendhtmlonly \\endhtmlonly
2717 \addindex \\endhtmlonly
2718 Ends a block of text that was started with a \ref cmdhtmlonly "\\htmlonly" command.
2720 \sa section \ref cmdhtmlonly "\\htmlonly".
2723 \section cmdendlatexonly \\endlatexonly
2725 \addindex \\endlatexonly
2726 Ends a block of text that was started with a \ref cmdlatexonly "\\latexonly" command.
2728 \sa section \ref cmdlatexonly "\\latexonly".
2731 \section cmdendmanonly \\endmanonly
2733 \addindex \\endmanonly
2734 Ends a block of text that was started with a \ref cmdmanonly "\\manonly" command.
2736 \sa section \ref cmdmanonly "\\manonly".
2739 \section cmdendrtfonly \\endrtfonly
2741 \addindex \\endrtfonly
2742 Ends a block of text that was started with a \ref cmdrtfonly "\\rtfonly" command.
2744 \sa section \ref cmdrtfonly "\\rtfonly".
2748 \section cmdendverbatim \\endverbatim
2750 \addindex \\endverbatim
2751 Ends a block of text that was started with a \ref cmdverbatim "\\verbatim" command.
2753 \sa section \ref cmdverbatim "\\verbatim".
2756 \section cmdendxmlonly \\endxmlonly
2758 \addindex \\endxmlonly
2759 Ends a block of text that was started with a \ref cmdxmlonly "\\xmlonly" command.
2761 \sa section \ref cmdxmlonly "\\xmlonly".
2764 \section cmdfdollar \\f$
2768 Marks the start and end of an in-text formula.
2769 \sa section \ref formulas "formulas" for an example.
2772 \section cmdfbropen \\f[
2776 Marks the start of a long formula that is displayed
2777 centered on a separate line.
2778 \sa section \ref cmdfbrclose "\\f]" and section \ref formulas "formulas".
2781 \section cmdfbrclose \\f]
2785 Marks the end of a long formula that is displayed
2786 centered on a separate line.
2787 \sa section \ref cmdfbropen "\\f[" and section \ref formulas "formulas".
2790 \section cmdfcurlyopen \\f{environment}{
2794 Marks the start of a formula that is in a specific environment.
2795 \note The second \c { is optional and is only to help editors (such as \c Vim) to
2796 do proper syntax highlighting by making the number of opening and closing braces
2798 \sa section \ref cmdfcurlyclose "\\f}" and section \ref formulas "formulas".
2801 \section cmdfcurlyclose \\f}
2805 Marks the end of a formula that is in a specific environment.
2806 \sa section \ref cmdfcurlyopen "\\f{" and section \ref formulas "formulas".
2809 \section cmdhtmlonly \\htmlonly ["[block]"]
2811 \addindex \\htmlonly
2812 Starts a block of text that will be verbatim included in the
2813 generated HTML documentation only. The block ends with a
2814 \ref cmdendhtmlonly "\\endhtmlonly" command.
2816 This command can be used to include HTML code that is too complex
2817 for doxygen (i.e. applets, java-scripts, and HTML tags that
2818 require specific attributes).
2820 Normally the contents between \ref cmdhtmlonly "\\htmlonly" and
2821 \ref cmdendhtmlonly "\\endhtmlonly" is inserted as-is. When you
2822 want to insert a HTML fragment that has block scope like a table or list
2823 which should appear outside \<p\>..\</p\>, this can lead to invalid HTML.
2824 You can use \\htmlonly[block] to make doxygen
2825 end the current paragraph and restart it after \\endhtmlonly.
2827 \note environment variables (like \$(HOME) ) are resolved inside a
2830 \sa section \ref cmdmanonly "\\manonly",
2831 \ref cmdlatexonly "\\latexonly",
2832 \ref cmdrtfonly "\\rtfonly",
2833 \ref cmdxmlonly "\\xmlonly", and
2834 \ref cmddocbookonly "\\docbookonly".
2837 \section cmdimage \\image <format> <file> ["caption"] [<sizeindication>=<size>]
2840 Inserts an image into the documentation. This command is format
2841 specific, so if you want to insert an image for more than one
2842 format you'll have to repeat this command for each format.
2844 The first argument specifies the output format. Currently, the
2845 following values are supported: \c html, \c latex and \c rtf.
2847 The second argument specifies the file name of the image.
2848 doxygen will look for files in the paths (or files) that you specified
2849 after the \ref cfg_image_path "IMAGE_PATH" tag.
2850 If the image is found it will be copied to the correct output directory.
2851 If the image name contains spaces you'll have to put quotes ("...") around it.
2852 You can also specify an absolute URL instead of a file name, but then
2853 doxygen does not copy the image nor check its existence.
2855 The third argument is optional and can be used to specify the caption
2856 that is displayed below the image. This argument has to be specified
2857 on a single line and between quotes even if it does not contain any
2858 spaces. The quotes are stripped before the caption is displayed.
2860 The fourth argument is also optional and can be used to specify the
2861 width or height of the image. This is only useful
2863 (i.e. format=<code>latex</code>). The \c sizeindication can be
2864 either \c width or \c height. The size should be a valid
2865 size specifier in \LaTeX (for example <code>10cm</code> or
2866 <code>6in</code> or a symbolic width like <code>\\textwidth</code>).
2868 Here is example of a comment block:
2871 /*! Here is a snapshot of my new application:
2872 * \image html application.jpg
2873 * \image latex application.eps "My application" width=10cm
2877 And this is an example of how the relevant part of the configuration file
2881 IMAGE_PATH = my_image_dir
2884 \warning The image format for HTML is limited to what your
2885 browser supports. For \LaTeX, the image format
2886 must be Encapsulated PostScript (eps).
2888 Doxygen does not check if the image is in the correct format.
2889 So \e you have to make sure this is the case!
2892 \section cmdlatexonly \\latexonly
2894 \addindex \\latexonly
2895 Starts a block of text that will be verbatim included in the
2896 generated \LaTeX documentation only. The block ends with a
2897 \ref cmdendlatexonly "\\endlatexonly" command.
2899 This command can be used to include \LaTeX code that is too
2900 complex for doxygen (i.e. images, formulas, special characters). You can
2901 use the \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly"
2902 pair to provide a proper HTML alternative.
2905 environment variables (like \$(HOME) ) are resolved inside a
2908 \sa sections \ref cmdrtfonly "\\rtfonly",
2909 \ref cmdxmlonly "\\xmlonly",
2910 \ref cmdmanonly "\\manonly",
2911 \ref cmdhtmlonly "\\htmlonly", and
2912 \ref cmdhtmlonly "\\docbookonly".
2915 \section cmdmanonly \\manonly
2918 Starts a block of text that will be verbatim included in the
2919 generated MAN documentation only. The block ends with a
2920 \ref cmdendmanonly "\\endmanonly" command.
2922 This command can be used to include groff code directly into
2923 MAN pages. You can use the \ref cmdhtmlonly "\\htmlonly" and
2924 \ref cmdendhtmlonly "\\endhtmlonly" and
2925 \ref cmdlatexonly "\\latexonly" and
2926 \ref cmdendlatexonly "\\endlatexonly" pairs to provide proper
2927 HTML and \LaTeX alternatives.
2929 \sa sections \ref cmdhtmlonly "\\htmlonly",
2930 \ref cmdxmlonly "\\xmlonly",
2931 \ref cmdrtfonly "\\rtfonly",
2932 \ref cmdlatexonly "\\latexonly", and
2933 \ref cmddocbookonly "\\docbookonly".
2936 \section cmdli \\li { item-description }
2939 This command has one argument that continues until the first
2940 blank line or until another \c \\li is encountered.
2941 The command can be used to generate a simple, not nested list of
2943 Each argument should start with a \c \\li command.
2948 \li \c AlignLeft left alignment.
2949 \li \c AlignCenter center alignment.
2950 \li \c AlignRight right alignment
2952 No other types of alignment are supported.
2954 will result in the following text:<br><br>
2956 <li> \c AlignLeft left alignment.
2957 <li> \c AlignCenter center alignment.
2958 <li> \c AlignRight right alignment
2960 No other types of alignment are supported.
2963 For nested lists, HTML commands should be used.
2965 Equivalent to \ref cmdarg "\\arg"
2971 Forces a new line. Equivalent to \<br\> and inspired by
2972 the \c printf function.
2975 \section cmdp \\p <word>
2978 Displays the parameter \<word\> using a typewriter font.
2979 You can use this command to refer to member function parameters in
2984 ... the \p x and \p y coordinates are used to ...
2986 This will result in the following text:<br><br>
2987 ... the \p x and \p y coordinates are used to ...
2989 Equivalent to \ref cmdc "\\c"
2990 To have multiple words in typewriter font use \<tt\>multiple words\</tt\>.
2993 \section cmdrtfonly \\rtfonly
2996 Starts a block of text that will be verbatim included in the
2997 generated RTF documentation only. The block ends with a
2998 \ref cmdendrtfonly "\\endrtfonly" command.
3000 This command can be used to include RTF code that is too complex
3004 environment variables (like \$(HOME) ) are resolved inside a
3007 \sa sections \ref cmdmanonly "\\manonly",
3008 \ref cmdxmlonly "\\xmlonly",
3009 \ref cmdlatexonly "\\latexonly",
3010 \ref cmdhtmlonly "\\htmlonly", and
3011 \ref cmddocbookonly "\\docbookonly".
3014 \section cmdverbatim \\verbatim
3016 \addindex \\verbatim
3017 Starts a block of text that will be verbatim included in
3018 the documentation. The block should end with a
3019 \ref cmdendverbatim "\\endverbatim" command.
3020 All commands are disabled in a verbatim block.
3022 \warning Make sure you include a \ref cmdendverbatim "\\endverbatim" command for each
3023 \c \\verbatim command or the parser will get confused!
3025 \sa sections \ref cmdcode "\\code",
3026 \ref cmdendverbatim "\\endverbatim", and
3027 \ref cmdverbinclude "\\verbinclude".
3030 \section cmdxmlonly \\xmlonly
3033 Starts a block of text that will be verbatim included in the
3034 generated XML output only. The block ends with a
3035 \ref cmdendxmlonly "\\endxmlonly" command.
3037 This command can be used to include custom XML tags.
3039 \sa sections \ref cmdmanonly "\\manonly",
3040 \ref cmdrtfonly "\\rtfonly",
3041 \ref cmdlatexonly "\\latexonly",
3042 \ref cmdhtmlonly "\\htmlonly", and
3043 \ref cmddocbookonly "\\docbookonly".
3046 \section cmdbackslash \\\\
3049 This command writes a backslash character (\c \\) to the
3050 output. The backslash has to be escaped in some
3051 cases because doxygen uses it to detect commands.
3057 This command writes an at-sign (\c \@) to the output.
3058 The at-sign has to be escaped in some cases
3059 because doxygen uses it to detect JavaDoc commands.
3062 \section cmdtilde \\~[LanguageId]
3064 This command enables/disables a language specific filter. This can be
3065 used to put documentation for different language into one comment block
3066 and use the \ref cfg_output_language "OUTPUT_LANGUAGE" tag to filter out only a specific language.
3067 Use \c \\~language_id to enable output for a specific language only and
3068 \c \\~ to enable output for all languages (this is also the default mode).
3072 /*! \~english This is English \~dutch Dit is Nederlands \~german Dies ist
3073 Deutsch. \~ output for all languages.
3079 \section cmdamp \\\&
3082 This command writes the \c \& character to the output.
3083 This character has to be escaped because it has a special meaning in HTML.
3086 \section cmddollar \\\$
3089 This command writes the \c \$ character to the output.
3090 This character has to be escaped in some cases, because it is used to expand
3091 environment variables.
3094 \section cmdhash \\\#
3097 This command writes the \c \# character to the output. This
3098 character has to be escaped in some cases, because it is used to refer
3099 to documented entities.
3105 This command writes the \c \< character to the output.
3106 This character has to be escaped because it has a special meaning in HTML.
3112 This command writes the \c \> character to the output. This
3113 character has to be escaped because it has a special meaning in HTML.
3116 \section cmdperc \\\%
3119 This command writes the \c \% character to the output. This
3120 character has to be escaped in some cases, because it is used to
3121 prevent auto-linking to word that is also a documented class or struct.
3124 \section cmdquot \\"
3127 This command writes the \c \" character to the output. This
3128 character has to be escaped in some cases, because it is used in pairs
3129 to indicate an unformatted text fragment.
3132 \section cmdchardot \\.
3135 This command writes a dot (`.`) to the output. This can be useful to
3136 prevent ending a brief description when JAVADOC_AUTOBRIEF is enabled
3137 or to prevent starting a numbered list when the dot follows a number at
3138 the start of a line.
3141 \section cmddcolon \\::
3144 This command writes a double colon (\c \::) to the output. This
3145 character sequence has to be escaped in some cases, because it is used
3146 to reference to documented entities.
3149 \section cmdpipe \\|
3152 This command writes a pipe symbol (\|) to the output. This
3153 character has to be escaped in some cases, because it is used
3154 for Markdown tables.
3157 \section cmdndash \\--
3160 This command writes two dashes (\--) to the output. This allows
3161 writing two consecutive dashes to the output instead of one n-dash character (--).
3164 \section cmdmdash \\---
3167 This command writes three dashes (\---) to the output. This allows
3168 writing three consecutuve dashes to the output instead of one m-dash character (---).
3171 \htmlonly <center> \endhtmlonly
3173 \htmlonly --- \endhtmlonly
3174 Commands included for Qt compatibility
3175 \htmlonly --- \endhtmlonly
3177 \htmlonly </center>\endhtmlonly
3179 The following commands are supported to remain compatible to the Qt class
3180 browser generator. Do \e not use these commands in your own documentation.
3182 <li>\\annotatedclasslist
3183 <li>\\classhierarchy
3187 <li>\\headerfilelist
3196 Go to the <a href="htmlcmds.html">next</a> section or return to the
3197 <a href="index.html">index</a>.