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 cmdendxmlonly \\endxmlonly
94 \refitem cmdenum \\enum
95 \refitem cmdexample \\example
96 \refitem cmdexception \\exception
97 \refitem cmdextends \\extends
98 \refitem cmdfdollar \\f\$
99 \refitem cmdfbropen \\f[
100 \refitem cmdfbrclose \\f]
101 \refitem cmdfcurlyopen \\f{
102 \refitem cmdfcurlyclose \\f}
103 \refitem cmdfile \\file
105 \refitem cmdheaderfile \\headerfile
106 \refitem cmdhideinitializer \\hideinitializer
107 \refitem cmdhtmlinclude \\htmlinclude
108 \refitem cmdhtmlonly \\htmlonly
109 \refitem cmdidlexcept \\idlexcept
111 \refitem cmdifnot \\ifnot
112 \refitem cmdimage \\image
113 \refitem cmdimplements \\implements
114 \refitem cmdinclude \\include
115 \refitem cmdincludelineno \\includelineno
116 \refitem cmdingroup \\ingroup
117 \refitem cmdinternal \\internal
118 \refitem cmdinvariant \\invariant
119 \refitem cmdinterface \\interface
120 \refitem cmdlatexinclude \\latexinclude
121 \refitem cmdlatexonly \\latexonly
123 \refitem cmdline \\line
124 \refitem cmdlink \\link
125 \refitem cmdmainpage \\mainpage
126 \refitem cmdmanonly \\manonly
127 \refitem cmdmemberof \\memberof
128 \refitem cmdmsc \\msc
129 \refitem cmdmscfile \\mscfile
131 \refitem cmdname \\name
132 \refitem cmdnamespace \\namespace
133 \refitem cmdnosubgrouping \\nosubgrouping
134 \refitem cmdnote \\note
135 \refitem cmdoverload \\overload
137 \refitem cmdpackage \\package
138 \refitem cmdpage \\page
139 \refitem cmdpar \\par
140 \refitem cmdparagraph \\paragraph
141 \refitem cmdparam \\param
142 \refitem cmdparblock \\parblock
143 \refitem cmdpost \\post
144 \refitem cmdpre \\pre
145 \refitem cmdprivate \\private
146 \refitem cmdprivatesection \\privatesection
147 \refitem cmdproperty \\property
148 \refitem cmdprotected \\protected
149 \refitem cmdprotectedsection \\protectedsection
150 \refitem cmdprotocol \\protocol
151 \refitem cmdpublic \\public
152 \refitem cmdpublicsection \\publicsection
153 \refitem cmdpure \\pure
154 \refitem cmdref \\ref
155 \refitem cmdrefitem \\refitem
156 \refitem cmdrelated \\related
157 \refitem cmdrelates \\relates
158 \refitem cmdrelatedalso \\relatedalso
159 \refitem cmdrelatesalso \\relatesalso
160 \refitem cmdremark \\remark
161 \refitem cmdremarks \\remarks
162 \refitem cmdresult \\result
163 \refitem cmdreturn \\return
164 \refitem cmdreturns \\returns
165 \refitem cmdretval \\retval
166 \refitem cmdrtfonly \\rtfonly
168 \refitem cmdsecreflist \\secreflist
169 \refitem cmdsection \\section
170 \refitem cmdsee \\see
171 \refitem cmdshort \\short
172 \refitem cmdshowinitializer \\showinitializer
173 \refitem cmdsince \\since
174 \refitem cmdskip \\skip
175 \refitem cmdskipline \\skipline
176 \refitem cmdsnippet \\snippet
177 \refitem cmdstruct \\struct
178 \refitem cmdsubpage \\subpage
179 \refitem cmdsubsection \\subsection
180 \refitem cmdsubsubsection \\subsubsection
181 \refitem cmdtableofcontents \\tableofcontents
182 \refitem cmdtest \\test
183 \refitem cmdthrow \\throw
184 \refitem cmdthrows \\throws
185 \refitem cmdtodo \\todo
186 \refitem cmdtparam \\tparam
187 \refitem cmdtypedef \\typedef
188 \refitem cmdunion \\union
189 \refitem cmduntil \\until
190 \refitem cmdvar \\var
191 \refitem cmdverbatim \\verbatim
192 \refitem cmdverbinclude \\verbinclude
193 \refitem cmdversion \\version
194 \refitem cmdvhdlflow \\vhdlflow
195 \refitem cmdwarning \\warning
196 \refitem cmdweakgroup \\weakgroup
197 \refitem cmdxmlonly \\xmlonly
198 \refitem cmdxrefitem \\xrefitem
199 \refitem cmddollar \\\$
201 \refitem cmdbackslash \\\\
203 \refitem cmdtilde \\~
206 \refitem cmdhash \\\#
207 \refitem cmdperc \\\%
208 \refitem cmdquot \\\"
209 \refitem cmdchardot \\\.
210 \refitem cmddcolon \::
212 \refitem cmdndash \\\--
213 \refitem cmdmdash \\\---
216 The following subsections provide a list of all commands that are recognized by
217 doxygen. Unrecognized commands are treated as normal text.
220 \htmlonly <center> \endhtmlonly
222 \htmlonly --- \endhtmlonly
223 Structural indicators
224 \htmlonly --- \endhtmlonly
226 \htmlonly </center> \endhtmlonly
228 \section cmdaddtogroup \\addtogroup <name> [(title)]
229 \addindex \\addtogroup
230 Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to
231 that command using the same \<name\> more than once will not result in a warning,
232 but rather one group with a merged documentation and the first title found in
235 The title is optional, so this command can also be used to add a number of
236 entities to an existing group using \c \@{ and \c \@} like this:
239 /*! \addtogroup mygrp
240 * Additional documentation for group 'mygrp'
251 /*! Another function */
259 \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup", and
260 \ref cmdweakgroup "\\weakgroup".
263 \section cmdcallgraph \\callgraph
265 \addindex \\callgraph
266 When this command is put in a comment block of a function or method
267 and \ref cfg_have_dot "HAVE_DOT" is set to \c YES, then doxygen will
268 generate a call graph for that function (provided the implementation of the
269 function or method calls other documented functions). The call graph will be
270 generated regardless of the value of \ref cfg_call_graph "CALL_GRAPH".
271 \note The completeness (and correctness) of the call graph depends on the
272 doxygen code parser which is not perfect.
274 \sa section \ref cmdcallergraph "\\callergraph".
277 \section cmdcallergraph \\callergraph
279 \addindex \\callergraph
280 When this command is put in a comment block of a function or method
281 and \ref cfg_have_dot "HAVE_DOT" is set to \c YES, then doxygen will
282 generate a caller graph for that function (provided the implementation of the
283 function or method calls other documented functions). The caller graph will be
284 generated regardless of the value of \ref cfg_caller_graph "CALLER_GRAPH".
285 \note The completeness (and correctness) of the caller graph depends on the
286 doxygen code parser which is not perfect.
288 \sa section \ref cmdcallgraph "\\callgraph".
291 \section cmdcategory \\category <name> [<header-file>] [<header-name>]
294 For Objective-C only: Indicates that a comment block contains documentation
295 for a class category with name \<name\>. The arguments are
296 equal to the \ref cmdclass "\\class" command.
298 \sa section \ref cmdclass "\\class".
301 \section cmdclass \\class <name> [<header-file>] [<header-name>]
304 Indicates that a comment block contains documentation for a
305 class with name \<name\>. Optionally a header file and a header name
306 can be specified. If the header-file is specified, a link to a verbatim copy
307 of the header will be included in the HTML documentation.
308 The \<header-name\> argument can be used to overwrite the
309 name of the link that is used in the class documentation to something other
310 than \<header-file\>. This can be useful if the include name is not located
311 on the default include path (like \<X11/X.h\>). With the \<header-name\>
312 argument you can also specify how the include statement should look like,
313 by adding either quotes or sharp brackets around the name.
314 Sharp brackets are used if just the name is given. Note that the
315 last two arguments can also be specified using
316 the \ref cmdheaderfile "\\headerfile" command.
321 Click <a href="$(DOXYGEN_DOCDIR)/examples/class/html/index.html">here</a>
322 for the corresponding HTML documentation that is generated by doxygen.
326 \section cmddef \\def <name>
329 Indicates that a comment block contains documentation for a
333 \verbinclude define.h
335 Click <a href="$(DOXYGEN_DOCDIR)/examples/define/html/define_8h.html">here</a>
336 for the corresponding HTML documentation that is generated by doxygen.
340 \section cmddefgroup \\defgroup <name> (group title)
343 Indicates that a comment block contains documentation for a
344 \ref modules "group" of classes, files or namespaces. This can be used to
345 categorize classes, files or namespaces, and document those
346 categories. You can also use groups as members of other groups,
347 thus building a hierarchy of groups.
349 The \<name\> argument should be a single-word identifier.
351 \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup", and
352 \ref cmdweakgroup "\\weakgroup".
355 \section cmddir \\dir [<path fragment>]
358 Indicates that a comment block contains documentation for a directory.
359 The "path fragment" argument should include the directory name and
360 enough of the path to be unique with respect to the other directories
362 The \ref cfg_strip_from_path "STRIP_FROM_PATH" option determines what is
363 stripped from the full path before it appears in the output.
366 \section cmdenum \\enum <name>
369 Indicates that a comment block contains documentation for an
370 enumeration, with name \<name\>. If the enum is a member of a class and
371 the documentation block is located outside the class definition,
372 the scope of the class should be specified as well.
373 If a comment block is located directly in front of an enum declaration,
374 the \c \\enum comment may be omitted.
377 The type of an anonymous enum cannot be documented, but the values
378 of an anonymous enum can.
383 Click <a href="$(DOXYGEN_DOCDIR)/examples/enum/html/class_test.html">here</a>
384 for the corresponding HTML documentation that is generated by doxygen.
388 \section cmdexample \\example <file-name>
391 Indicates that a comment block contains documentation for a source code
392 example. The name of the source file is \<file-name\>. The text of
393 this file will be included in the documentation, just after the
394 documentation contained in the comment block. All examples are placed
395 in a list. The source code is scanned for documented members and classes.
396 If any are found, the names are cross-referenced with the documentation.
397 Source files or directories can be specified using the
398 \ref cfg_example_path "EXAMPLE_PATH"
399 tag of doxygen's configuration file.
401 If \<file-name\> itself is not unique for the set of example files specified
403 \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part of the absolute path
406 If more than one source file is needed for the example,
407 the \ref cmdinclude "\\include" command can be used.
410 \verbinclude example.cpp
411 Where the example file \c example_test.cpp looks as follows:
412 \verbinclude example_test.cpp
414 Click <a href="$(DOXYGEN_DOCDIR)/examples/example/html/examples.html">here</a>
415 for the corresponding HTML documentation that is generated by doxygen.
418 \sa section \ref cmdinclude "\\include".
421 \section cmdendinternal \\endinternal
423 \addindex \\endinternal
424 This command ends a documentation fragment that was started with a
425 \ref cmdinternal "\\internal" command. The text between \ref cmdinternal "\\internal" and
426 \c \\endinternal will only be visible
427 if \ref cfg_internal_docs "INTERNAL_DOCS" is set to \c YES.
430 \section cmdextends \\extends <name>
433 This command can be used to manually indicate an inheritance relation,
434 when the programming language does not support this concept natively
437 The file \c manual.c in the example directory shows how to use this command.
440 Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a>
441 for the corresponding HTML documentation that is generated by doxygen.
444 \sa section \ref cmdimplements "\\implements" and section
445 \ref cmdmemberof "\\memberof"
448 \section cmdfile \\file [<name>]
451 Indicates that a comment block contains documentation for a source or
452 header file with name \<name\>. The file name may include (part of) the
453 path if the file-name alone is not unique. If the file name is omitted
454 (i.e. the line after \c \\file is left blank) then the documentation block that
455 contains the \c \\file command will belong to the file it is located in.
458 The documentation of global functions, variables, typedefs, and enums will
459 only be included in the output if the file they are in is documented as well.
464 Click <a href="$(DOXYGEN_DOCDIR)/examples/file/html/file_8h.html">here</a>
465 for the corresponding HTML documentation that is generated by doxygen.
468 \note In the above example \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF"
469 has been set to \c YES in the configuration file.
472 \section cmdfn \\fn (function declaration)
475 Indicates that a comment block contains documentation for a function
476 (either global or as a member of a class). This command is \em only
477 needed if a comment block is \e not placed in front (or behind)
478 the function declaration or definition.
480 If your comment block \e is in front of the function
481 declaration or definition this command can (and to avoid redundancy
484 A full function declaration including arguments should be specified after the
485 \c \\fn command on a \e single line, since the argument ends at the end
488 This command is equivalent to \ref cmdvar "\\var", \ref cmdtypedef "\\typedef",
489 and \ref cmdproperty "\\property".
491 \warning Do not use this command
492 if it is not absolutely needed, since it will lead to duplication of
493 information and thus to errors.
498 Click <a href="$(DOXYGEN_DOCDIR)/examples/func/html/class_test.html">here</a>
499 for the corresponding HTML documentation that is generated by doxygen.
503 \sa sections \ref cmdvar "\\var", \ref cmdproperty "\\property", and
504 \ref cmdtypedef "\\typedef".
507 \section cmdheaderfile \\headerfile <header-file> [<header-name>]
509 \addindex \\headerfile
510 Intended to be used for class, struct, or union documentation, where
511 the documentation is in front of the definition. The arguments of
512 this command are the same as the second and third argument of
513 \ref cmdclass "\\class".
514 The \<header-file\> name refers to the file that should be included by the
515 application to obtain the definition of the class, struct, or union.
516 The \<header-name\> argument can be used to overwrite the
517 name of the link that is used in the class documentation to something other
518 than \<header-file\>. This can be useful if the include name is not located
519 on the default include path (like \<X11/X.h\>).
521 With the \<header-name\>
522 argument you can also specify how the include statement should look like,
523 by adding either double quotes or sharp brackets around the name.
524 By default sharp brackets are used if just the name is given.
526 If a pair of double quotes is given for either the \<header-file\> or
527 \<header-name\> argument, the current file (in which the command was found)
528 will be used but with quotes. So for a comment block with a \c \\headerfile
529 command inside a file <code>test.h</code>, the following three commands are equivalent:
531 \headerfile test.h "test.h"
532 \headerfile test.h ""
533 \headerfile "" \endverbatim
534 To get sharp brackets you do not need to specify anything,
535 but if you want to be explicit you could use any of the following:
537 \headerfile test.h <test.h>
538 \headerfile test.h <>
539 \headerfile <> \endverbatim
541 To globally reverse the default include representation to
542 local includes you can set
543 \ref cfg_force_local_includes "FORCE_LOCAL_INCLUDES" to \c YES.
545 To disable the include information altogether set
546 \ref cfg_show_include_files "SHOW_INCLUDE_FILES" to \c NO.
549 \section cmdhideinitializer \\hideinitializer
551 \addindex \\hideinitializer
552 By default the value of a define and the initializer of a variable
553 are displayed unless they are longer than 30 lines. By putting
554 this command in a comment block of a define or variable, the
555 initializer is always hidden. The maximum number of initialization lines
556 can be changed by means of the configuration parameter
557 \ref cfg_max_initializer_lines "MAX_INITIALIZER_LINES", the default
560 \sa section \ref cmdshowinitializer "\\showinitializer".
563 \section cmdidlexcept \\idlexcept <name>
564 \addindex \\idlexcept
566 Indicates that a comment block contains documentation for a
567 IDL exception with name \<name\>.
570 \section cmdimplements \\implements <name>
572 \addindex \\implements
573 This command can be used to manually indicate an inheritance relation,
574 when the programming language does not support this concept natively
577 The file \c manual.c in the example directory shows how to use this command.
580 Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a>
581 for the corresponding HTML documentation that is generated by doxygen.
584 \sa section \ref cmdextends "\\extends" and section
585 \ref cmdmemberof "\\memberof"
588 \section cmdingroup \\ingroup (<groupname> [<groupname> <groupname>])
591 If the \c \\ingroup command is placed in a comment block of a
592 class, file or namespace, then it will be added to the group or
593 groups identified by \<groupname\>.
595 \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup",
596 \ref cmdaddtogroup "\\addtogroup", and \ref cmdweakgroup "\\weakgroup"
599 \section cmdinterface \\interface <name> [<header-file>] [<header-name>]
601 \addindex \\interface
602 Indicates that a comment block contains documentation for an
603 interface with name \<name\>. The arguments are equal to the arguments of the
604 \ref cmdclass "\\class" command.
606 \sa section \ref cmdclass "\\class".
609 \section cmdinternal \\internal
612 This command starts a documentation fragment that is meant for internal
613 use only. The fragment naturally ends at the end of the comment block.
614 You can also force the internal section to end earlier by using the
615 \ref cmdendinternal "\\endinternal" command.
617 If the \c \\internal command is put inside a section
618 (see for example \ref cmdsection "\\section") all subsections after the
619 command are considered to be internal as well. Only a new section at the
620 same level will end the fragment that is considered internal.
622 You can use \ref cfg_internal_docs "INTERNAL_DOCS" in the config file
623 to show (\c YES) or hide (\c NO) the internal documentation.
625 \sa section \ref cmdendinternal "\\endinternal".
629 \section cmdmainpage \\mainpage [(title)]
633 If the \c \\mainpage command is placed in a comment block the
634 block is used to customize the index page (in HTML) or
635 the first chapter (in \LaTeX).
637 The title argument is optional and replaces the default title that
638 doxygen normally generates. If you do not want any title you can
639 specify \c notitle as the argument of \c \\mainpage.
643 /*! \mainpage My Personal Index Page
645 * \section intro_sec Introduction
647 * This is the introduction.
649 * \section install_sec Installation
651 * \subsection step1 Step 1: Opening the box
657 You can refer to the main page using: <code>\ref cmdref "\\ref" index</code>.
659 \sa section \ref cmdsection "\\section",
660 section \ref cmdsubsection "\\subsection", and
661 section \ref cmdpage "\\page".
664 \section cmdmemberof \\memberof <name>
667 This command makes a function a member of a class in a similar way
668 as \ref cmdrelates "\\relates" does, only with this command the function
669 is represented as a real member of the class.
670 This can be useful when the programming language does not support
671 the concept of member functions natively (e.g. C).
673 It is also possible to use this command together with
674 \ref cmdpublic "\\public", \ref cmdprotected "\\protected" or
675 \ref cmdprivate "\\private".
677 The file \c manual.c in the example directory shows how to use this command.
680 Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a>
681 for the corresponding HTML documentation that is generated by doxygen.
684 \sa sections \ref cmdextends "\\extends", \ref cmdimplements "\\implements",
685 \ref cmdpublic "\\public", \ref cmdprotected "\\protected" and
686 \ref cmdprivate "\\private".
689 \section cmdname \\name [(header)]
693 This command turns a comment block into a header
694 definition of a member group. The
695 comment block should be followed by a
696 <code>//\@{ ... //\@}</code> block containing the
697 members of the group.
699 See section \ref memgroup for an example.
702 \section cmdnamespace \\namespace <name>
704 \addindex \\namespace
705 Indicates that a comment block contains documentation for a
706 namespace with name \<name\>.
709 \section cmdnosubgrouping \\nosubgrouping
711 \addindex \\nosubgrouping
712 This command can be put in the documentation
713 of a class. It can be used in combination with member grouping
714 to avoid that doxygen puts a member group as a subgroup of a
715 Public/Protected/Private/... section.
717 \sa sections \ref cmdpublicsection "\\publicsection",
718 \ref cmdprotectedsection "\\protectedsection" and
719 \ref cmdprivatesection "\\privatesection".
722 \section cmdoverload \\overload [(function declaration)]
725 This command can be used to generate the following
726 standard text for an overloaded member function:
728 > This is an overloaded member function, provided for convenience.
729 > It differs from the above function only in what argument(s) it accepts.
731 If the documentation for the overloaded member function is not located
732 in front of the function declaration or definition, the optional
733 argument should be used to specify the correct function.
735 Any other documentation that is inside the documentation block will
736 by appended after the generated message.
739 You are responsible that there is indeed an
740 earlier documented member that is overloaded by this one.
741 To prevent that document reorders the documentation you should set
742 \ref cfg_sort_member_docs "SORT_MEMBER_DOCS" to \c NO in this case.
744 The \c \\overload command does not work inside a one-line comment.
746 \verbinclude examples/overload.cpp
748 Click <a href="$(DOXYGEN_DOCDIR)/examples/overload/html/class_test.html">here</a>
749 for the corresponding HTML documentation that is generated by doxygen.
753 \section cmdpackage \\package <name>
756 Indicates that a comment block contains documentation for a
757 Java package with name \<name\>.
760 \section cmdpage \\page <name> (title)
763 Indicates that a comment block contains a piece of documentation that is
764 not directly related to one specific class, file or member.
765 The HTML generator creates a page containing the documentation. The
767 starts a new section in the chapter 'Page documentation'.
770 \verbinclude page.doc
772 Click <a href="$(DOXYGEN_DOCDIR)/examples/page/html/pages.html">here</a>
773 for the corresponding HTML documentation that is generated by doxygen.
777 The \<name\> argument consists of a combination of letters and number
778 digits. If you wish to use upper case letters (e.g. \c MYPAGE1), or
779 mixed case letters (e.g. \c MyPage1) in the \<name\> argument, you
780 should set \ref cfg_case_sense_names "CASE_SENSE_NAMES" to \c YES. However, this is advisable
781 only if your file system is case sensitive. Otherwise (and for better
782 portability) you should use all lower case letters (e.g. \c mypage1)
783 for \<name\> in all references to the page.
785 \sa section \ref cmdsection "\\section", section
786 \ref cmdsubsection "\\subsection", and section
790 \section cmdprivate \\private
793 Indicates that the member documented by the comment block is private,
794 i.e., should only be accessed by other members in the same class.
796 Note that Doxygen automatically detects the protection level of members
797 in object-oriented languages. This command is intended for use only when
798 the language does not support the concept of protection level natively
801 For starting a section of private members, in a way similar to the
802 "private:" class marker in C++, use \ref cmdprivatesection "\\privatesection".
804 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
805 \ref cmdprotected "\\protected" and \ref cmdprivatesection "\\privatesection".
808 \section cmdprivatesection \\privatesection
810 \addindex \\privatesection
811 Starting a section of private members, in a way similar to the
812 "private:" class marker in C++.
813 Indicates that the member documented by the comment block is private,
814 i.e., should only be accessed by other members in the same class.
816 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
817 \ref cmdprotected "\\protected" and \ref cmdprivate "\\private".
820 \section cmdproperty \\property (qualified property name)
823 Indicates that a comment block contains documentation for a
824 property (either global or as a member of a class).
825 This command is equivalent to \ref cmdfn "\\fn",
826 \ref cmdtypedef "\\typedef", and \ref cmdvar "\\var".
828 \sa sections \ref cmdfn "\\fn", \ref cmdtypedef "\\typedef", and
832 \section cmdprotected \\protected
834 \addindex \\protected
835 Indicates that the member documented by the comment block is protected,
836 i.e., should only be accessed by other members in the same or derived
839 Note that Doxygen automatically detects the protection level of members
840 in object-oriented languages. This command is intended for use only when
841 the language does not support the concept of protection level natively
844 For starting a section of protected members, in a way similar to the
845 "protected:" class marker in C++, use \ref cmdprotectedsection "\\protectedsection".
847 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
848 \ref cmdprivate "\\private" and \ref cmdprotectedsection "\\protectedsection".
851 \section cmdprotectedsection \\protectedsection
853 \addindex \\protectedsection
854 Starting a section of protected members, in a way similar to the
855 "protected:" class marker in C++.
856 Indicates that the member documented by the comment block is protected,
857 i.e., should only be accessed by other members in the same or derived
860 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public",
861 \ref cmdprivate "\\private" and \ref cmdprotected "\\protected".
864 \section cmdprotocol \\protocol <name> [<header-file>] [<header-name>]
867 Indicates that a comment block contains documentation for a
868 protocol in Objective-C with name \<name\>. The arguments are equal
869 to the \ref cmdclass "\\class" command.
871 \sa section \ref cmdclass "\\class".
874 \section cmdpublic \\public
877 Indicates that the member documented by the comment block is public,
878 i.e., can be accessed by any other class or function.
880 Note that Doxygen automatically detects the protection level of members
881 in object-oriented languages. This command is intended for use only when
882 the language does not support the concept of protection level natively
885 For starting a section of public members, in a way similar to the
886 "public:" class marker in C++, use \ref cmdpublicsection "\\publicsection".
888 \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected",
889 \ref cmdprivate "\\private" and \ref cmdpublicsection "\\publicsection".
892 \section cmdpublicsection \\publicsection
894 \addindex \\publicsection
895 Starting a section of public members, in a way similar to the
896 "public:" class marker in C++.
897 Indicates that the member documented by the comment block is public,
898 i.e., can be accessed by any other class or function.
900 \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected",
901 \ref cmdprivate "\\private" and \ref cmdpublic "\\public".
904 \section cmdpure \\pure
907 Indicates that the member documented by the comment block is pure virtual,
908 i.e., it is abstract and has no implementation associated with it.
910 This command is intended for use only when
911 the language does not support the concept of pure virtual methods natively
915 \section cmdrelates \\relates <name>
918 This command can be used in the documentation of a non-member function
919 \<name\>. It puts the function inside the 'related function' section
920 of the class documentation. This command is useful for documenting
921 non-friend functions that are nevertheless strongly coupled to a certain
922 class. It prevents the need of having to document a file, but
923 only works for functions.
926 \verbinclude relates.cpp
928 Click <a href="$(DOXYGEN_DOCDIR)/examples/relates/html/class_string.html">here</a>
929 for the corresponding HTML documentation that is generated by doxygen.
933 \section cmdrelated \\related <name>
936 Equivalent to \ref cmdrelates "\\relates"
939 \section cmdrelatesalso \\relatesalso <name>
941 \addindex \\relatesalso
942 This command can be used in the documentation of a non-member function
943 \<name\>. It puts the function both inside the 'related function' section
944 of the class documentation as well as leaving it at its normal file documentation
945 location. This command is useful for documenting
946 non-friend functions that are nevertheless strongly coupled to a certain
947 class. It only works for functions.
950 \section cmdrelatedalso \\relatedalso <name>
952 \addindex \\relatedalso
953 Equivalent to \ref cmdrelatesalso "\\relatesalso"
956 \section cmdshowinitializer \\showinitializer
958 \addindex \\showinitializer
959 By default the value of a define and the initializer of a variable
960 are only displayed if they are less than 30 lines long. By putting
961 this command in a comment block of a define or variable, the
962 initializer is shown unconditionally.
963 The maximum number of initialization lines
964 can be changed by means of the configuration parameter
965 \ref cfg_max_initializer_lines "MAX_INITIALIZER_LINES", the default value is
968 \sa section \ref cmdhideinitializer "\\hideinitializer".
971 \section cmdstatic \\static
974 Indicates that the member documented by the comment block is static,
975 i.e., it works on a class, instead of on an instance of the class.
977 This command is intended for use only when
978 the language does not support the concept of static methods natively (e.g. C).
981 \section cmdstruct \\struct <name> [<header-file>] [<header-name>]
984 Indicates that a comment block contains documentation for a
985 struct with name \<name\>. The arguments are equal to the arguments of the
986 \ref cmdclass "\\class" command.
988 \sa section \ref cmdclass "\\class".
991 \section cmdtypedef \\typedef (typedef declaration)
994 Indicates that a comment block contains documentation for a
995 typedef (either global or as a member of a class).
996 This command is equivalent to \ref cmdfn "\\fn",
997 \ref cmdproperty "\\property", and \ref cmdvar "\\var".
999 \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and
1000 \ref cmdvar "\\var".
1003 \section cmdunion \\union <name> [<header-file>] [<header-name>]
1006 Indicates that a comment block contains documentation for a
1007 union with name \<name\>. The arguments are equal to the arguments of the
1008 \ref cmdclass "\\class" command.
1010 \sa section \ref cmdclass "\\class".
1013 \section cmdvar \\var (variable declaration)
1016 Indicates that a comment block contains documentation for a variable or
1017 enum value (either global or as a member of a class).
1018 This command is equivalent to \ref cmdfn "\\fn",
1019 \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef".
1021 \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef".
1024 \section cmdvhdlflow \\vhdlflow [(title for the flow chart)]
1026 \addindex \\vhdlflow
1027 This is a VHDL specific command, which can be put in the documentation of a process to
1028 produce a flow chart of the logic in the process.
1029 Optionally a title for the flow chart can be given.
1030 \note Currently the flow chart will only appear in the HTML output.
1033 \section cmdweakgroup \\weakgroup <name> [(title)]
1034 \addindex \\addtogroup
1035 Can be used exactly like \ref cmdaddtogroup "\\addtogroup", but has
1036 a lower priority when it comes to resolving conflicting grouping
1039 \sa page \ref grouping "Grouping" and section \ref cmdaddtogroup "\\addtogroup".
1043 \htmlonly <center> \endhtmlonly
1045 \htmlonly --- \endhtmlonly
1047 \htmlonly --- \endhtmlonly
1049 \htmlonly </center>\endhtmlonly
1052 \section cmdattention \\attention { attention text }
1054 \addindex \\attention
1055 Starts a paragraph where a message that needs attention may be entered.
1056 The paragraph will be indented.
1057 The text of the paragraph has no special internal structure. All visual
1058 enhancement commands may be used inside the paragraph.
1059 Multiple adjacent \c \\attention commands will be joined into a single paragraph.
1060 The \c \\attention command ends when a blank line or some other
1061 sectioning command is encountered.
1064 \section cmdauthor \\author { list of authors }
1067 Starts a paragraph where one or more author names may be entered.
1068 The paragraph will be indented.
1069 The text of the paragraph has no special internal structure. All visual
1070 enhancement commands may be used inside the paragraph.
1071 Multiple adjacent \c \\author commands will be joined into a single paragraph.
1072 Each author description will start a new line. Alternatively, one \c \\author command
1073 may mention several authors. The \c \\author command ends when a blank line or some other
1074 sectioning command is encountered.
1077 \verbinclude author.cpp
1079 Click <a href="$(DOXYGEN_DOCDIR)/examples/author/html/class_some_nice_class.html">here</a>
1080 for the corresponding HTML documentation that is generated by doxygen.
1084 \section cmdauthors \\authors { list of authors }
1087 Equivalent to \ref cmdauthor "\\author".
1090 \section cmdbrief \\brief { brief description }
1093 Starts a paragraph that serves as a brief description. For classes and files
1094 the brief description will be used in lists and at the start of the
1095 documentation page. For class and file members, the brief description
1096 will be placed at the declaration of the member and prepended to the
1097 detailed description. A brief description may span several lines (although
1098 it is advised to keep it brief!). A brief description ends when a
1099 blank line or another sectioning command is encountered. If multiple
1100 \c \\brief commands are present they will be joined. See section
1101 \ref cmdauthor "\\author" for an example.
1103 Synonymous to \ref cmdshort "\\short".
1106 \section cmdbug \\bug { bug description }
1109 Starts a paragraph where one or more bugs may be reported.
1110 The paragraph will be indented.
1111 The text of the paragraph has no special internal structure. All visual
1112 enhancement commands may be used inside the paragraph.
1113 Multiple adjacent \c \\bug commands will be joined into a single paragraph.
1114 Each bug description will start on a new line.
1115 Alternatively, one \c \\bug command may mention
1116 several bugs. The \c \\bug command ends when a blank line or some other
1117 sectioning command is encountered. See section \ref cmdauthor "\\author"
1121 \section cmdcond \\cond [(section-label)]
1124 Starts a conditional section that ends with a corresponding
1125 \ref cmdendcond "\\endcond" command, which is typically found in
1126 another comment block. The main purpose of this pair of
1127 commands is to (conditionally) exclude part of a file from processing
1128 (in older version of doxygen this could only be achieved using C preprocessor commands).
1130 The section between \c \\cond and \ref cmdendcond "\\endcond" can be included by
1131 adding its section label to the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1132 configuration option. If the section label is omitted, the section will
1133 be excluded from processing unconditionally. The section label can be a
1134 logical expression build of section labels, round brackets, && (AND), || (OR) and ! (NOT).
1135 If you use an expression you need to wrap it in round brackets, i.e
1136 <tt>\\cond (!LABEL1 && LABEL2)</tt>.
1138 For conditional sections within a comment block one should
1139 use a \ref cmdif "\\if" ... \ref cmdendif "\\endif" block.
1141 Conditional sections can be nested. In this case a nested section will only
1142 be shown if it and its containing section are included.
1144 Here is an example showing the commands in action:
1152 virtual void func() = 0;
1156 /** A method used for testing */
1157 virtual void test() = 0;
1164 * The implementation of the interface
1166 class Implementation : public Intf
1176 /** This method is obsolete and does
1177 * not show up in the documentation.
1186 The output will be different depending on whether or not \ref cfg_enabled_sections "ENABLED_SECTIONS"
1187 contains \c TEST, or \c DEV
1189 \sa sections \ref cmdendcond "\\endcond" and \ref cfg_enabled_sections "ENABLED_SECTIONS".
1192 \section cmdcopyright \\copyright { copyright description }
1194 \addindex \\copyright
1195 Starts a paragraph where the copyright of an entity can be described.
1196 This paragraph will be indented.
1197 The text of the paragraph has no special internal structure.
1198 See section \ref cmdauthor "\\author" for an example.
1201 \section cmddate \\date { date description }
1204 Starts a paragraph where one or more dates may be entered.
1205 The paragraph will be indented.
1206 The text of the paragraph has no special internal structure. All visual
1207 enhancement commands may be used inside the paragraph.
1208 Multiple adjacent \c \\date commands will be joined into a single paragraph.
1209 Each date description will start on a new line.
1210 Alternatively, one \c \\date command may mention
1211 several dates. The \c \\date command ends when a blank line or some other
1212 sectioning command is encountered. See section \ref cmdauthor "\\author"
1216 \section cmddeprecated \\deprecated { description }
1218 \addindex \\deprecated
1219 Starts a paragraph indicating that this documentation block belongs to
1220 a deprecated entity. Can be used to describe alternatives,
1221 expected life span, etc.
1224 \section cmddetails \\details { detailed description }
1227 Just like \ref cmdbrief "\\brief" starts a brief description, \c \\details
1228 starts the detailed description. You can also start a new paragraph (blank line)
1229 then the \c \\details command is not needed.
1232 \section cmdelse \\else
1235 Starts a conditional section if the previous conditional section
1236 was not enabled. The previous section should have been started with
1237 a \ref cmdif "\\if", \ref cmdifnot "\\ifnot", or \ref cmdelseif "\\elseif"
1240 \sa \ref cmdif "\\if", \ref cmdifnot "\\ifnot", \ref cmdelseif "\\elseif",
1241 \ref cmdendif "\\endif."
1244 \section cmdelseif \\elseif (section-label)
1247 Starts a conditional documentation section if the previous section
1248 was not enabled. A conditional section is
1249 disabled by default. To enable it you must put the
1250 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1251 tag in the configuration file. The section label can be a logical expression
1252 build of section names, round brackets, && (AND), || (OR) and ! (NOT).
1253 Conditional blocks can be nested. A nested section is
1254 only enabled if all enclosing sections are enabled as well.
1256 \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot",
1257 \ref cmdelse "\\else", and \ref cmdelseif "\\elseif".
1260 \section cmdendcond \\endcond
1263 Ends a conditional section that was started by \ref cmdcond "\\cond".
1265 \sa section \ref cmdcond "\\cond".
1268 \section cmdendif \\endif
1271 Ends a conditional section that was started by \ref cmdif "\\if" or \ref cmdifnot "\\ifnot"
1272 For each \ref cmdif "\\if" or \ref cmdifnot "\\ifnot" one and only one matching
1273 \ref cmdendif "\\endif" must follow.
1275 \sa sections \ref cmdif "\\if" and \ref cmdifnot "\\ifnot".
1278 \section cmdexception \\exception <exception-object> { exception description }
1280 \addindex \\exception
1281 Starts an exception description for an exception object with name
1282 \<exception-object\>. Followed by a description of the exception.
1283 The existence of the exception object is not checked.
1284 The text of the paragraph has no special internal structure. All visual
1285 enhancement commands may be used inside the paragraph.
1286 Multiple adjacent \c \\exception commands will be joined into a single paragraph.
1287 Each exception description will start on a new line.
1288 The \c \\exception description ends when a blank line or some other
1289 sectioning command is encountered. See section \ref cmdfn "\\fn" for an
1293 \section cmdif \\if (section-label)
1296 Starts a conditional documentation section. The section ends
1297 with a matching \ref cmdendif "\\endif" command. A conditional section is
1298 disabled by default. To enable it you must put the
1299 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1300 tag in the configuration file.
1302 The section label can be a logical expression
1303 build of section names, round brackets, && (AND), || (OR) and ! (NOT).
1304 If you use an expression you need to wrap it in round brackets, i.e
1305 <tt>\\cond (!LABEL1 && LABEL2)</tt>.
1307 Conditional blocks can be nested. A nested section is
1308 only enabled if all enclosing sections are enabled as well.
1312 /*! Unconditionally shown documentation.
1314 * Only included if Cond1 is set.
1317 * Only included if Cond2 is set.
1319 * Only included if Cond2 and Cond3 are set.
1323 * Unconditional text.
1327 You can also use conditional commands inside aliases. To
1328 document a class in two languages you could for instance use:
1336 * Dit is Nederlands.
1344 Where the following aliases are defined in the configuration file:
1347 ALIASES = "english=\if english" \
1348 "endenglish=\endif" \
1353 and \ref cfg_enabled_sections "ENABLED_SECTIONS" can be used to enable either \c english or \c dutch.
1355 \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot",
1356 \ref cmdelse "\\else", \ref cmdelseif "\\elseif", and
1357 \ref cfg_enabled_sections "ENABLED_SECTIONS".
1360 \section cmdifnot \\ifnot (section-label)
1363 Starts a conditional documentation section. The section ends
1364 with a matching \ref cmdendif "\\endif" command. This conditional section is
1365 enabled by default. To disable it you must put the
1366 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS"
1367 tag in the configuration file. The section label can be a logical expression
1368 build of section names, round brackets, && (AND), || (OR) and ! (NOT).
1370 \sa sections \ref cmdendif "\\endif", \ref cmdif "\\if",
1371 \ref cmdelse "\\else", and \ref cmdelseif "\\elseif", and
1372 \ref cfg_enabled_sections "ENABLED_SECTIONS".
1375 \section cmdinvariant \\invariant { description of invariant }
1377 \addindex \\invariant
1378 Starts a paragraph where the invariant of an entity can be described.
1379 The paragraph will be indented.
1380 The text of the paragraph has no special internal structure. All visual
1381 enhancement commands may be used inside the paragraph.
1382 Multiple adjacent \c \\invariant commands will be joined into a single paragraph.
1383 Each invariant description will start on a new line.
1384 Alternatively, one \c \\invariant command may mention
1385 several invariants. The \c \\invariant command ends when a blank line or some other
1386 sectioning command is encountered.
1389 \section cmdnote \\note { text }
1392 Starts a paragraph where a note can be entered. The paragraph will be
1393 indented. The text of the paragraph has no special internal structure.
1394 All visual enhancement commands may be used inside the paragraph.
1395 Multiple adjacent \c \\note commands will be joined into a single paragraph.
1396 Each note description will start on a new line.
1397 Alternatively, one \c \\note command may mention
1398 several notes. The \c \\note command ends when a blank line or some other
1399 sectioning command is encountered. See section \ref cmdpar "\\par"
1403 \section cmdpar \\par [(paragraph title)] { paragraph }
1406 If a paragraph title is given this command starts a paragraph with a
1407 user defined heading. The heading extends until the end of the
1408 line. The paragraph following the command will be indented.
1410 If no paragraph title is given this command will start a new paragraph.
1411 This will also work inside other paragraph commands
1412 (like \ref cmdparam "\\param" or \ref cmdwarning "\\warning") without ending that command.
1414 The text of the paragraph has no special internal structure. All visual
1415 enhancement commands may be used inside the paragraph.
1416 The \c \\par command ends when a blank line or some other
1417 sectioning command is encountered.
1420 \verbinclude par.cpp
1422 Click <a href="$(DOXYGEN_DOCDIR)/examples/par/html/class_test.html">here</a>
1423 for the corresponding HTML documentation that is generated by doxygen.
1427 \section cmdparam \\param [(dir)] <parameter-name> { parameter description }
1430 Starts a parameter description for a function parameter with name
1431 \<parameter-name\>, followed by a description of the parameter.
1432 The existence of the parameter is checked and a warning is given if
1433 the documentation of this (or any other) parameter is missing or not
1434 present in the function declaration or definition.
1436 The \c \\param command has an optional attribute, (dir), specifying the direction
1437 of the parameter. Possible values are "[in]", "[in,out]", and "[out]",
1438 note the [square] brackets in this description.
1439 When a parameter is both input and output, [in,out] is used as attribute.
1440 Here is an example for the function \c memcpy:
1443 * Copies bytes from a source memory area to a destination memory area,
1444 * where both areas may not overlap.
1445 * @param[out] dest The memory area to copy to.
1446 * @param[in] src The memory area to copy from.
1447 * @param[in] n The number of bytes to copy
1449 void memcpy(void *dest, const void *src, size_t n);
1452 The parameter description is a paragraph with no special internal structure.
1453 All visual enhancement commands may be used inside the paragraph.
1455 Multiple adjacent \c \\param commands will be joined into a single paragraph.
1456 Each parameter description will start on a new line.
1457 The \c \\param description ends when a blank line or some other
1458 sectioning command is encountered. See section \ref cmdfn "\\fn" for an
1461 Note that you can also document multiple parameters with a single
1462 \c \\param command using a comma separated list. Here is an example:
1465 /** Sets the position.
1466 * @param x,y,z Coordinates of the position in 3D space.
1468 void setPosition(double x,double y,double z,double t)
1473 Note that for PHP one can also specify the type (or types if you
1474 separate them with a pipe symbol) which are allowed for a parameter
1475 (as this is not part of the definition).
1476 The syntax is the same as for phpDocumentor, i.e.
1478 @param datatype1|datatype2 $paramname description
1482 \section cmdparblock \\parblock
1483 \addindex \\parblock
1484 For commands that expect a single paragraph as argument
1485 (such as \ref cmdpar "\\par", \ref cmdparam "\\param" and \ref cmdwarning "\\warning"),
1486 the \ref cmdparblock "\\parblock" command allows to start a
1487 description that covers multiple paragraphs, which then ends with
1488 \ref cmdendparblock "\\endparblock".
1492 /** Example of a param command with a description consisting of two paragraphs
1495 * First paragraph of the param description.
1497 * Second paragraph of the param description.
1499 * Rest of the comment block continues.
1502 Note that the \c \\parblock command may also appear directly after
1503 \ref cmdparam "\\param"'s first argument.
1506 \section cmdendparblock \\endparblock
1507 \addindex \\endparblock
1508 This ends a block of paragraphs started with \ref cmdparblock "\\parblock".
1511 \section cmdtparam \\tparam <template-parameter-name> { description }
1514 Starts a template parameter for a class or function template parameter
1515 with name \<template-parameter-name\>, followed by a description of the
1518 Otherwise similar to \ref cmdparam "\\param".
1521 \section cmdpost \\post { description of the postcondition }
1524 Starts a paragraph where the postcondition of an entity can be described.
1525 The paragraph will be indented.
1526 The text of the paragraph has no special internal structure. All visual
1527 enhancement commands may be used inside the paragraph.
1528 Multiple adjacent \c \\post commands will be joined into a single paragraph.
1529 Each postcondition will start on a new line.
1530 Alternatively, one \c \\post command may mention
1531 several postconditions. The \c \\post command ends when a blank line or some other
1532 sectioning command is encountered.
1535 \section cmdpre \\pre { description of the precondition }
1538 Starts a paragraph where the precondition of an entity can be described.
1539 The paragraph will be indented.
1540 The text of the paragraph has no special internal structure. All visual
1541 enhancement commands may be used inside the paragraph.
1542 Multiple adjacent \c \\pre commands will be joined into a single paragraph.
1543 Each precondition will start on a new line.
1544 Alternatively, one \c \\pre command may mention
1545 several preconditions. The \c \\pre command ends when a blank line or some other
1546 sectioning command is encountered.
1549 \section cmdremark \\remark { remark text }
1552 Starts a paragraph where one or more remarks may be entered.
1553 The paragraph will be indented.
1554 The text of the paragraph has no special internal structure. All visual
1555 enhancement commands may be used inside the paragraph.
1556 Multiple adjacent \c \\remark commands will be joined into a single paragraph.
1557 Each remark will start on a new line.
1558 Alternatively, one \c \\remark command may mention
1559 several remarks. The \c \\remark command ends when a blank line or some other
1560 sectioning command is encountered.
1563 \section cmdremarks \\remarks { remark text }
1566 Equivalent to \ref cmdremark "\\remark".
1569 \section cmdresult \\result { description of the result value }
1572 Equivalent to \ref cmdreturn "\\return".
1575 \section cmdreturn \\return { description of the return value }
1578 Starts a return value description for a function.
1579 The text of the paragraph has no special internal structure. All visual
1580 enhancement commands may be used inside the paragraph.
1581 Multiple adjacent \c \\return commands will be joined into a single paragraph.
1582 The \c \\return description ends when a blank line or some other
1583 sectioning command is encountered. See section \ref cmdfn "\\fn" for an
1587 \section cmdreturns \\returns { description of the return value }
1590 Equivalent to \ref cmdreturn "\\return".
1593 \section cmdretval \\retval <return value> { description }
1596 Starts a description for a function's return value with name
1597 \<return value\>, followed by a description of the return value.
1598 The text of the paragraph that forms the description has no special
1599 internal structure. All visual enhancement commands may be used inside the
1601 Multiple adjacent \c \\retval commands will be joined into a single paragraph.
1602 Each return value description will start on a new line.
1603 The \c \\retval description ends when a blank line or some other
1604 sectioning command is encountered.
1607 \section cmdsa \\sa { references }
1610 Starts a paragraph where one or more cross-references to classes,
1611 functions, methods, variables, files or URL may be specified.
1612 Two names joined by either <code>::</code> or <code>\#</code>
1613 are understood as referring to a class and one of its members.
1614 One of several overloaded methods or constructors
1615 may be selected by including a parenthesized list of argument types after
1618 Synonymous to \ref cmdsee "\\see".
1620 \sa section \ref autolink "autolink" for information on how to create links
1624 \section cmdsee \\see { references }
1627 Equivalent to \ref cmdsa "\\sa". Introduced for compatibility with Javadoc.
1630 \section cmdshort \\short { short description }
1633 Equivalent to \ref cmdbrief "\\brief".
1636 \section cmdsince \\since { text }
1639 This command can be used to specify since when (version or time) an
1640 entity is available. The paragraph that follows \c \\since does not have any
1641 special internal structure. All visual enhancement commands may be
1642 used inside the paragraph. The \c \\since description ends when a blank
1643 line or some other sectioning command is encountered.
1646 \section cmdtest \\test { paragraph describing a test case }
1649 Starts a paragraph where a test case can be described.
1650 The description will also add the test case to a separate test list.
1651 The two instances of the description will be cross-referenced.
1652 Each test case in the test list will be preceded by a header that
1653 indicates the origin of the test case.
1656 \section cmdthrow \\throw <exception-object> { exception description }
1659 Synonymous \ref cmdexception "\\exception".
1662 the command \ref cmdthrows "\\throws" is a synonym for this command.
1664 \sa section \ref cmdexception "\\exception"
1667 \section cmdthrows \\throws <exception-object> { exception description }
1670 Equivalent to \ref cmdthrow "\\throw".
1673 \section cmdtodo \\todo { paragraph describing what is to be done }
1676 Starts a paragraph where a TODO item is described.
1677 The description will also add an item to a separate TODO list.
1678 The two instances of the description will be cross-referenced.
1679 Each item in the TODO list will be preceded by a header that
1680 indicates the origin of the item.
1683 \section cmdversion \\version { version number }
1686 Starts a paragraph where one or more version strings may be entered.
1687 The paragraph will be indented.
1688 The text of the paragraph has no special internal structure. All visual
1689 enhancement commands may be used inside the paragraph.
1690 Multiple adjacent \c \\version commands will be joined into a single paragraph.
1691 Each version description will start on a new line.
1692 Alternatively, one \c \\version command may mention
1693 several version strings.
1694 The \\version command ends when a blank line or some other
1695 sectioning command is encountered.
1696 See section \ref cmdauthor "\\author" for an example.
1699 \section cmdwarning \\warning { warning message }
1702 Starts a paragraph where one or more warning messages may be entered.
1703 The paragraph will be indented.
1704 The text of the paragraph has no special internal structure. All visual
1705 enhancement commands may be used inside the paragraph.
1706 Multiple adjacent \c \\warning commands will be joined into a single paragraph.
1707 Each warning description will start on a new line.
1708 Alternatively, one \c \\warning command may mention
1709 several warnings. The \c \\warning command ends when a blank line or some other
1710 sectioning command is encountered. See section \ref cmdauthor "\\author"
1714 \section cmdxrefitem \\xrefitem <key> "(heading)" "(list title)" { text }
1716 \addindex \\xrefitem
1717 This command is a generalization of commands such as \ref cmdtodo "\\todo"
1718 and \ref cmdbug "\\bug".
1719 It can be used to create user-defined text sections which are automatically
1720 cross-referenced between the place of occurrence and a related page,
1721 which will be generated. On the related page all sections of
1722 the same type will be collected.
1724 The first argument \<key\> is an
1725 identifier uniquely representing the type of the section. The second argument
1726 is a quoted string representing the heading of the section under which
1727 text passed as the fourth argument is put. The third argument (list title)
1728 is used as the title for the related page containing all items with the
1729 same key. The keys \c "todo", \c "test", \c "bug" and \c "deprecated" are predefined.
1731 To get an idea on how to use the \c \\xrefitem command and what its effect
1732 is, consider the todo list, which (for English output) can be seen an
1733 alias for the command
1734 \verbatim \xrefitem todo "Todo" "Todo List" \endverbatim
1736 Since it is very tedious and error-prone to repeat the first three
1737 parameters of the command for each section, the command is meant to
1738 be used in combination with the \ref cfg_aliases "ALIASES" option in the
1740 To define a new command \c \\reminder, for instance, one should add the following
1741 line to the configuration file:
1742 \verbatim ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" \endverbatim
1743 Note the use of escaped quotes for the second and third argument of the
1744 \c \\xrefitem command.
1746 In case parameter "(heading)" is the empty string no heading is generated. This can be useful
1747 when used in combination with the \ref cmdpage "\\page" command e.g.
1749 /** @page my_errors My Errors
1750 * @brief Errors page
1752 * Errors page contents.
1755 /** \error ERROR 101: in case a file can not be opened.
1756 Check about file system read/write access. */
1757 #define MY_ERR_CANNOT_OPEN_FILE 101
1759 /** \error ERROR 102: in case a file can not be closed.
1760 Check about file system read/write access. */
1761 #define MY_ERR_CANNOT_CLOSE_FILE 102
1763 with \c \\error defined as
1764 \verbatim ALIASES += "error=\xrefitem my_errors \"\" \"\"" \endverbatim
1768 \htmlonly <center> \endhtmlonly
1770 \htmlonly --- \endhtmlonly
1771 Commands to create links
1772 \htmlonly --- \endhtmlonly
1774 \htmlonly </center>\endhtmlonly
1777 \section cmdaddindex \\addindex (text)
1779 \addindex \\addindex
1780 This command adds (text) to the \LaTeX index.
1783 \section cmdanchor \\anchor <word>
1786 This command places an invisible, named anchor into the documentation
1787 to which you can refer with the \ref cmdref "\\ref" command.
1789 \note Anchors can currently only be put into a comment block
1790 that is marked as a page (using \ref cmdpage "\\page") or mainpage
1791 (\ref cmdmainpage "\\mainpage").
1793 \sa section \ref cmdref "\\ref".
1796 \section cmdcite \\cite <label>
1799 Adds a bibliographic reference in the text and in the list of bibliographic
1800 references. The \<label\> must be a valid BibTeX label that can be found
1801 in one of the .bib files listed in \ref cfg_cite_bib_files "CITE_BIB_FILES".
1802 For the \LaTeX output the formatting of the reference in the text can be
1803 configured with \ref cfg_latex_bib_style "LATEX_BIB_STYLE". For other
1804 output formats a fixed representation is used. Note that using this
1805 command requires the \c bibtex tool to be present in the search path.
1808 \section cmdendlink \\endlink
1811 This command ends a link that is started with the \ref cmdlink "\\link" command.
1813 \sa section \ref cmdlink "\\link".
1816 \section cmdlink \\link <link-object>
1819 The links that are automatically generated by doxygen always have the
1820 name of the object they point to as link-text.
1822 The \c \\link command can be used to create a link to an object (a file,
1823 class, or member) with a user specified link-text.
1824 The link command should end with an \ref cmdendlink "\\endlink" command. All text between
1825 the \c \\link and \ref cmdendlink "\\endlink" commands serves as text for a link to
1826 the \<link-object\> specified as the first argument of \c \\link.
1828 \sa Section \ref autolink "autolink" for more information on automatically
1829 generated links and valid link-objects.
1832 \section cmdref \\ref <name> ["(text)"]
1835 Creates a reference to a named section, subsection, page or anchor.
1836 For HTML documentation the reference command will generate a link to
1837 the section. For a section or subsection the title of the section will be
1838 used as the text of the link. For an anchor the optional text between quotes
1839 will be used or \<name\> if no text is specified.
1840 For \LaTeX documentation the reference command will
1841 generate a section number for sections or the text followed by a
1842 page number if \<name\> refers to an anchor.
1845 Section \ref cmdpage "\\page" for an example of the \c \\ref command.
1848 \section cmdrefitem \\refitem <name>
1850 Just like the \ref cmdref "\\ref" command, this command creates a reference
1851 to a named section, but this reference appears in a list that is started by
1852 \ref cmdsecreflist "\\secreflist"
1853 and ends with \ref cmdendsecreflist "\\endsecreflist".
1854 An example of such a list can be seen
1855 \ref showsecreflist "at the top of the page".
1858 \section cmdsecreflist \\secreflist
1859 \addindex \\secreflist
1860 Starts an index list of item, created with \ref cmdrefitem "\\refitem"
1861 that each link to a named section.
1864 \section cmdendsecreflist \\endsecreflist
1865 \addindex \\endsecreflist
1866 End an index list started with \ref cmdsecreflist "\\secreflist".
1869 \section cmdsubpage \\subpage <name> ["(text)"]
1872 This command can be used to create a hierarchy of pages. The
1873 same structure can be made using the \ref cmddefgroup "\\defgroup" and
1874 \ref cmdingroup "\\ingroup" commands, but for pages the \c \\subpage command
1875 is often more convenient. The main page (see \ref cmdmainpage "\\mainpage")
1876 is typically the root of hierarchy.
1878 This command behaves similar as \ref cmdref "\\ref" in the sense that
1879 it creates a reference to a page labeled \<name\> with the optional
1880 link text as specified in the second argument.
1882 It differs from the \ref cmdref "\\ref" command in that it only works for pages,
1883 and creates a parent-child relation between pages, where the
1884 child page (or sub page) is identified by label \<name\>.
1886 See the \ref cmdsection "\\section"
1887 and \ref cmdsubsection "\\subsection" commands if you want to add structure
1888 without creating multiple pages.
1890 \note Each page can be the sub page of only one other page and
1891 no cyclic relations are allowed, i.e. the page hierarchy must have a tree
1896 /*! \mainpage A simple manual
1900 This manual is divided in the following sections:
1902 - \subpage advanced "Advanced usage"
1905 //-----------------------------------------------------------
1907 /*! \page intro Introduction
1908 This page introduces the user to the topic.
1909 Now you can proceed to the \ref advanced "advanced section".
1912 //-----------------------------------------------------------
1914 /*! \page advanced Advanced Usage
1915 This page is for advanced users.
1916 Make sure you have first read \ref intro "the introduction".
1921 \section cmdtableofcontents \\tableofcontents
1923 \addindex \\tableofcontents
1924 Creates a table of contents at the top of a page, listing all
1925 sections and subsections in the page.
1927 \warning This command only works inside related page documentation and
1928 \e not in other documentation blocks and only has effect in the
1932 \section cmdsection \\section <section-name> (section title)
1935 Creates a section with name \<section-name\>. The title of the
1936 section should be specified as the second argument of the \c \\section
1939 \warning This command only works inside related page documentation and
1940 \e not in other documentation blocks!
1943 Section \ref cmdpage "\\page" for an example of the
1944 \c \\section command.
1947 \section cmdsubsection \\subsection <subsection-name> (subsection title)
1949 \addindex \\subsection
1950 Creates a subsection with name \<subsection-name\>. The title of the
1951 subsection should be specified as the second argument of the \c \\subsection
1954 \warning This command only works inside a section of a related page
1955 documentation block and
1956 \e not in other documentation blocks!
1959 Section \ref cmdpage "\\page" for an example of the
1960 \c \\subsection command.
1963 \section cmdsubsubsection \\subsubsection <subsubsection-name> (subsubsection title)
1965 \addindex \\subsubsection
1966 Creates a subsubsection with name \<subsubsection-name\>. The title of the
1967 subsubsection should be specified as the second argument of the
1968 \c \\subsubsection command.
1970 \warning This command only works inside a subsection of a
1971 related page documentation block and
1972 \e not in other documentation blocks!
1975 Section \ref cmdpage "\\page" for an example of the
1976 \ref cmdsection "\\section" command and
1977 \ref cmdsubsection "\\subsection" command.
1980 \section cmdparagraph \\paragraph <paragraph-name> (paragraph title)
1982 \addindex \\paragraph
1983 Creates a named paragraph with name \<paragraph-name\>. The title of the
1984 paragraph should be specified as the second argument of the
1985 \c \\paragraph command.
1987 \warning This command only works inside a subsubsection of a
1988 related page documentation block and
1989 \e not in other documentation blocks!
1993 \htmlonly <center> \endhtmlonly
1995 \htmlonly --- \endhtmlonly
1996 Commands for displaying examples
1997 \htmlonly --- \endhtmlonly
1999 \htmlonly </center>\endhtmlonly
2002 \section cmddontinclude \\dontinclude <file-name>
2004 \addindex \\dontinclude
2005 This command can be used to parse a source file without actually
2006 verbatim including it in the documentation (as the \ref cmdinclude "\\include" command does).
2007 This is useful if you want to divide the source file into smaller pieces and
2008 add documentation between the pieces.
2009 Source files or directories can be specified using the
2010 \ref cfg_example_path "EXAMPLE_PATH"
2011 tag of doxygen's configuration file.
2013 The class and member declarations and definitions inside the code fragment
2014 are 'remembered' during the parsing of the comment block that contained
2015 the \c \\dontinclude command.
2017 For line by line descriptions of source files, one or more lines
2018 of the example can be displayed using the \ref cmdline "\\line",
2019 \ref cmdskip "\\skip", \ref cmdskipline "\\skipline", and
2020 \ref cmduntil "\\until" commands. An internal pointer is used for these commands. The
2021 \c \\dontinclude command sets the pointer to the first line of the example.
2024 \verbinclude include.cpp
2025 Where the example file \c example_test.cpp looks as follows:
2026 \verbinclude example_test.cpp
2028 Click <a href="$(DOXYGEN_DOCDIR)/examples/include/html/example.html">here</a>
2029 for the corresponding HTML documentation that is generated by doxygen.
2032 Alternatively, the \ref cmdsnippet "\\snippet" command can be used to
2033 include only a fragment of a source file. For this to work the
2034 fragment has to be marked.
2036 \sa sections \ref cmdline "\\line", \ref cmdskip "\\skip",
2037 \ref cmdskipline "\\skipline", \ref cmduntil "\\until", and
2038 \ref cmdinclude "\\include".
2041 \section cmdinclude \\include <file-name>
2044 This command can be used to include a source file as a block of code.
2045 The command takes the name of an include file as an argument.
2046 Source files or directories can be specified using the
2047 \ref cfg_example_path "EXAMPLE_PATH"
2048 tag of doxygen's configuration file.
2050 If \<file-name\> itself is not unique for the set of example files specified
2051 by the \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part
2052 of the absolute path to disambiguate it.
2054 Using the \c \\include command is equivalent to inserting the file into
2055 the documentation block and surrounding it
2056 with \ref cmdcode "\\code" and \ref cmdendcode "\\endcode" commands.
2058 The main purpose of the \c \\include command is to avoid code
2059 duplication in case of example blocks that consist of multiple
2060 source and header files.
2062 For a line by line description of a source files use the
2063 \ref cmddontinclude "\\dontinclude" command in combination with
2064 the \ref cmdline "\\line", \ref cmdskip "\\skip",
2065 \ref cmdskipline "\\skipline",
2066 and \ref cmduntil "\\until" commands.
2068 Alternatively, the \ref cmdsnippet "\\snippet" command can be used to
2069 include only a fragment of a source file. For this to work the
2070 fragment has to be marked.
2072 \note Doxygen's special commands do not work inside blocks of code.
2073 It is allowed to nest C-style comments inside a code block though.
2075 \sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude", and
2076 \ref cmdverbatim "\\verbatim".
2079 \section cmdincludelineno \\includelineno <file-name>
2081 \addindex \\includelineno
2082 This command works the same way as \ref cmdinclude "\\include", but will add line
2083 numbers to the included file.
2085 \sa section \ref cmdinclude "\\include".
2088 \section cmdline \\line ( pattern )
2091 This command searches line by line through the example that was last
2092 included using \ref cmdinclude "\\include" or
2093 \ref cmddontinclude "\\dontinclude" until it finds a non-blank
2094 line. If that line contains the specified pattern, it is written
2097 The internal pointer that is used to keep track of the current line in
2098 the example, is set to the start of the line following the non-blank
2099 line that was found (or to the end of the example if no such line could
2102 See section \ref cmddontinclude "\\dontinclude" for an example.
2105 \section cmdskip \\skip ( pattern )
2108 This command searches line by line through the example that was last
2109 included using \ref cmdinclude "\\include" or
2110 \ref cmddontinclude "\\dontinclude" until it finds a line that contains
2111 the specified pattern.
2113 The internal pointer that is used to keep track of the current line in
2114 the example, is set to the start of the line that contains the specified
2115 pattern (or to the end of the example if the pattern could not be found).
2117 See section \ref cmddontinclude "\\dontinclude" for an example.
2120 \section cmdskipline \\skipline ( pattern )
2122 \addindex \\skipline
2123 This command searches line by line through the example that was last
2124 included using \ref cmdinclude "\\include" or
2125 \ref cmddontinclude "\\dontinclude" until it finds a line that contains
2126 the specified pattern. It then writes the line to the output.
2128 The internal pointer that is used to keep track of the current line in
2129 the example, is set to the start of the line following the line that is
2130 written (or to the end of the example if the pattern could not be found).
2134 \verbatim\skipline pattern\endverbatim
2138 \line pattern\endverbatim
2140 See section \ref cmddontinclude "\\dontinclude" for an example.
2143 \section cmdsnippet \\snippet <file-name> ( block_id )
2146 Where the \ref cmdinclude "\\include" command can be used to include
2147 a complete file as source code, this command can be used to quote only
2148 a fragment of a source file.
2150 For example, the putting the following command in the documentation,
2151 references a snippet in file \c example.cpp residing in a subdirectory
2152 which should be pointed to by \ref cfg_example_path "EXAMPLE_PATH".
2155 \snippet snippets/example.cpp Adding a resource
2158 The text following the file name is the unique identifier for the snippet.
2159 This is used to delimit the quoted code in the relevant snippet file as
2160 shown in the following example that corresponds to the above \c \\snippet
2164 QImage image(64, 64, QImage::Format_RGB32);
2165 image.fill(qRgb(255, 160, 128));
2167 //! [Adding a resource]
2168 document->addResource(QTextDocument::ImageResource,
2169 QUrl("mydata://image.png"), QVariant(image));
2170 //! [Adding a resource]
2174 Note that the lines containing the block markers will not be included,
2175 so the output will be:
2178 document->addResource(QTextDocument::ImageResource,
2179 QUrl("mydata://image.png"), QVariant(image));
2182 Note also that the [block_id] markers should appear exactly twice in the
2185 see section \ref cmddontinclude "\\dontinclude" for an alternative way
2186 to include fragments of a source file that does not require markers.
2189 \section cmduntil \\until ( pattern )
2192 This command writes all lines of the example that was last
2193 included using \ref cmdinclude "\\include" or
2194 \ref cmddontinclude "\\dontinclude" to the output, until it finds
2195 a line containing the specified pattern. The line containing the pattern
2196 will be written as well.
2198 The internal pointer that is used to keep track of the current line in
2199 the example, is set to the start of the line following last written
2200 line (or to the end of the example if the pattern could not be found).
2202 See section \ref cmddontinclude "\\dontinclude" for an example.
2205 \section cmdverbinclude \\verbinclude <file-name>
2207 \addindex \\verbinclude
2208 This command includes the file \<file-name\> verbatim in the documentation.
2209 The command is equivalent to pasting the file in the documentation and
2210 placing \ref cmdverbatim "\\verbatim" and \ref cmdendverbatim "\\endverbatim"
2213 Files or directories that doxygen should look for can be specified using the
2214 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
2217 \section cmdhtmlinclude \\htmlinclude <file-name>
2219 \addindex \\htmlinclude
2220 This command includes the file \<file-name\> as is in the HTML documentation.
2221 The command is equivalent to pasting the file in the documentation and
2222 placing \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly"
2225 Files or directories that doxygen should look for can be specified using the
2226 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
2230 \section cmdlatexinclude \\latexinclude <file-name>
2232 \addindex \\latexinclude
2233 This command includes the file \<file-name\> as is in the \LaTeX documentation.
2234 The command is equivalent to pasting the file in the documentation and
2235 placing \ref cmdlatexonly "\\latexonly" and \ref cmdendlatexonly "\\endlatexonly"
2238 Files or directories that doxygen should look for can be specified using the
2239 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
2243 \htmlonly <center> \endhtmlonly
2245 \htmlonly --- \endhtmlonly
2246 Commands for visual enhancements
2247 \htmlonly --- \endhtmlonly
2249 \htmlonly </center>\endhtmlonly
2251 \section cmda \\a <word>
2254 Displays the argument \<word\> in italics.
2255 Use this command to emphasize words.
2256 Use this command to refer to member arguments in the running text.
2260 ... the \a x and \a y coordinates are used to ...
2262 This will result in the following text:<br><br>
2263 ... the \a x and \a y coordinates are used to ...
2265 Equivalent to \ref cmde "\\e" and \ref cmdem "\\em".
2266 To emphasize multiple words use \<em\>multiple words\</em\>.
2269 \section cmdarg \\arg { item-description }
2272 This command has one argument that continues until the first
2273 blank line or until another \c \\arg is encountered.
2274 The command can be used to generate a simple, not nested list of
2276 Each argument should start with a \c \\arg command.
2281 \arg \c AlignLeft left alignment.
2282 \arg \c AlignCenter center alignment.
2283 \arg \c AlignRight right alignment
2285 No other types of alignment are supported.
2287 will result in the following text:<br><br>
2289 <li> \c AlignLeft left alignment.
2290 <li> \c AlignCenter center alignment.
2291 <li> \c AlignRight right alignment
2293 No other types of alignment are supported.
2296 For nested lists, HTML commands should be used.
2298 Equivalent to \ref cmdli "\\li"
2302 \section cmdb \\b <word>
2305 Displays the argument \<word\> using a bold font.
2306 Equivalent to \<b\>word\</b\>.
2307 To put multiple words in bold use \<b\>multiple words\</b\>.
2310 \section cmdc \\c <word>
2313 Displays the argument \<word\> using a typewriter font.
2314 Use this to refer to a word of code.
2315 Equivalent to \<tt\>word\</tt\>.
2320 ... This function returns \c void and not \c int ...
2322 will result in the following text:<br><br>
2323 ... This function returns \c void and not \c int ...
2325 Equivalent to \ref cmdp "\\p"
2326 To have multiple words in typewriter font use \<tt\>multiple words\</tt\>.
2329 \section cmdcode \\code [ '{'<word>'}']
2332 Starts a block of code. A code block is treated differently
2333 from ordinary text. It is interpreted as source code. The names of
2334 classes and members and other documented entities are automatically
2335 replaced by links to the documentation.
2337 By default the language that is assumed for syntax highlighting is based
2338 on the location where the \c \\code block was found. If this part of
2339 a Python file for instance, the syntax highlight will be done according
2340 to the Python syntax.
2342 If it unclear from the context which language is meant (for instance the
2343 comment is in a <code>.txt</code> or <code>.markdown</code> file) then you can also explicitly
2344 indicate the language, by putting the file extension typically
2345 that doxygen associated with the language in curly brackets after the
2346 code block. Here is an example:
2359 \sa section \ref cmdendcode "\\endcode" and section \ref cmdverbatim "\\verbatim".
2362 \section cmdcopydoc \\copydoc <link-object>
2365 Copies a documentation block from the object specified by \<link-object\>
2366 and pastes it at the location of the command. This command can be useful
2367 to avoid cases where a documentation block would otherwise have to be
2368 duplicated or it can be used to extend the documentation of an inherited
2371 The link object can point to a member (of a class, file or group),
2372 a class, a namespace, a group, a page, or a file (checked in that order).
2373 Note that if the object pointed to is a member (function, variable,
2374 typedef, etc), the compound (class, file, or group) containing it
2375 should also be documented for the copying to work.
2377 To copy the documentation for a member of a
2378 class one can, for instance, put the following in the documentation:
2381 /*! @copydoc MyClass::myfunction()
2382 * More documentation.
2386 if the member is overloaded, you should specify the argument types
2387 explicitly (without spaces!), like in the following:
2390 //! @copydoc MyClass::myfunction(type1,type2)
2393 Qualified names are only needed if the context in which the documentation
2394 block is found requires them.
2396 The \c \\copydoc command can be used recursively, but cycles in the \c \\copydoc
2397 relation will be broken and flagged as an error.
2399 Note that <code>\\copydoc foo()</code> is roughly equivalent to doing:
2401 \brief \copybrief foo()
2402 \details \copydetails foo()
2404 See \ref cmdcopybrief "\\copybrief" and
2405 \ref cmdcopydetails "\\copydetails" for copying only the brief or
2406 detailed part of the comment block.
2409 \section cmdcopybrief \\copybrief <link-object>
2411 \addindex \\copybrief
2412 Works in a similar way as \ref cmdcopydoc "\\copydoc" but will
2413 only copy the brief description, not the detailed documentation.
2416 \section cmdcopydetails \\copydetails <link-object>
2418 \addindex \\copydetails
2419 Works in a similar way as \ref cmdcopydoc "\\copydoc" but will
2420 only copy the detailed documentation, not the brief description.
2423 \section cmddocbookonly \\docbookonly
2425 \addindex \\docbookonly
2426 Starts a block of text that will be verbatim included in the
2427 generated docbook documentation only. The block ends with a
2428 \ref cmdenddocbookonly "\\enddocbookonly" command.
2430 \sa section \ref cmdmanonly "\\manonly",
2431 \ref cmdlatexonly "\\latexonly",
2432 \ref cmdrtfonly "\\rtfonly",
2433 \ref cmdxmlonly "\\xmlonly", and
2434 \ref cmdhtmlonly "\\htmlonly".
2437 \section cmddot \\dot
2440 Starts a text fragment which should contain a valid description of a
2441 dot graph. The text fragment ends with \ref cmdenddot "\\enddot".
2442 Doxygen will pass the text on to dot and include the resulting
2443 image (and image map) into the output.
2444 The nodes of a graph can be made clickable by using the URL attribute.
2445 By using the command \ref cmdref "\\ref" inside the URL value you can conveniently
2446 link to an item inside doxygen. Here is an example:
2456 * Class relations expressed via an inline dot graph:
2459 * node [shape=record, fontname=Helvetica, fontsize=10];
2460 * b [ label="class B" URL="\ref B"];
2461 * c [ label="class C" URL="\ref C"];
2462 * b -> c [ arrowhead="open", style="dashed" ];
2465 * Note that the classes in the above graph are clickable
2466 * (in the HTML output).
2471 \section cmdmsc \\msc
2474 Starts a text fragment which should contain a valid description of a
2475 message sequence chart. See http://www.mcternan.me.uk/mscgen/ for examples.
2476 The text fragment ends with \ref cmdendmsc "\\endmsc".
2477 \note The text fragment should only include the part of the message
2478 sequence chart that is
2479 within the <code>msc {...}</code> block.
2480 \note You need to install the <code>mscgen</code> tool, if you want to use this
2483 Here is an example of the use of the \c \\msc command.
2485 /** Sender class. Can be used to send a command to the server.
2486 * The receiver will acknowledge the command by calling Ack().
2489 * Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"];
2490 * Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"];
2496 /** Acknowledgment from server */
2500 /** Receiver class. Can be used to receive and execute commands.
2501 * After execution of a command, the receiver will send an acknowledgment
2504 * Receiver<-Sender [label="Command()", URL="\ref Command()"];
2505 * Receiver->Sender [label="Ack()", URL="\ref Sender::Ack()", ID="1"];
2511 /** Executable a command on the server */
2512 void Command(int commandId);
2517 \sa section \ref cmdmscfile "\\mscfile".
2520 \section cmddotfile \\dotfile <file> ["caption"]
2523 Inserts an image generated by dot from \<file\> into the documentation.
2525 The first argument specifies the file name of the image.
2526 doxygen will look for files in the paths (or files) that you specified
2527 after the \ref cfg_dotfile_dirs "DOTFILE_DIRS" tag.
2528 If the dot file is found it will be used as an input file to the dot tool.
2529 The resulting image will be put into the correct output directory.
2530 If the dot file name contains spaces you'll have to put quotes ("...") around it.
2532 The second argument is optional and can be used to specify the caption
2533 that is displayed below the image. This argument has to be specified
2534 between quotes even if it does not contain any spaces. The quotes are
2535 stripped before the caption is displayed.
2538 \section cmdmscfile \\mscfile <file> ["caption"]
2541 Inserts an image generated by mscgen from \<file\> into the documentation.
2542 See http://www.mcternan.me.uk/mscgen/ for examples.
2544 The first argument specifies the file name of the image.
2545 doxygen will look for files in the paths (or files) that you specified
2546 after the \ref cfg_mscfile_dirs "MSCFILE_DIRS" tag.
2547 If the msc file is found it will be used as an input file to the mscgen tool.
2548 The resulting image will be put into the correct output directory.
2549 If the msc file name contains spaces you'll have to put quotes ("...") around it.
2551 The second argument is optional and can be used to specify the caption
2552 that is displayed below the image. This argument has to be specified
2553 between quotes even if it does not contain any spaces. The quotes are
2554 stripped before the caption is displayed.
2556 \sa section \ref cmdmsc "\\msc".
2559 \section cmddiafile \\diafile <file> ["caption"]
2562 Inserts an image made in dia from \<file\> into the documentation.
2564 The first argument specifies the file name of the image.
2565 doxygen will look for files in the paths (or files) that you specified
2566 after the \ref cfg_diafile_dirs "DIAFILE_DIRS" tag.
2567 If the dia file is found it will be used as an input file dia.
2568 The resulting image will be put into the correct output directory.
2569 If the dia file name contains spaces you'll have to put quotes ("...") around it.
2571 The second argument is optional and can be used to specify the caption
2572 that is displayed below the image. This argument has to be specified
2573 between quotes even if it does not contain any spaces. The quotes are
2574 stripped before the caption is displayed.
2577 \section cmde \\e <word>
2580 Displays the argument \<word\> in italics.
2581 Use this command to emphasize words.
2586 ... this is a \e really good example ...
2588 will result in the following text:<br><br>
2589 ... this is a \e really good example ...
2591 Equivalent to \ref cmda "\\a" and \ref cmdem "\\em".
2592 To emphasize multiple words use \<em\>multiple words\</em\>.
2595 \section cmdem \\em <word>
2598 Displays the argument \<word\> in italics.
2599 Use this command to emphasize words.
2604 ... this is a \em really good example ...
2606 will result in the following text:<br><br>
2607 ... this is a \em really good example ...
2609 Equivalent to \ref cmda "\\a" and \ref cmde "\\e".
2610 To emphasize multiple words use \<em\>multiple words\</em\>.
2613 \section cmdendcode \\endcode
2616 Ends a block of code.
2617 \sa section \ref cmdcode "\\code"
2620 \section cmdenddocbookonly \\enddocbookonly
2622 \addindex \\enddocbookonly
2623 Ends a block of text that was started with a \ref cmddocbookonly "\\docbookonly" command.
2625 \sa section \ref cmddocbookonly "\\docbookonly".
2628 \section cmdenddot \\enddot
2631 Ends a block that was started with \ref cmddot "\\dot".
2634 \section cmdendmsc \\endmsc
2637 Ends a block that was started with \ref cmdmsc "\\msc".
2640 \section cmdendhtmlonly \\endhtmlonly
2642 \addindex \\endhtmlonly
2643 Ends a block of text that was started with a \ref cmdhtmlonly "\\htmlonly" command.
2645 \sa section \ref cmdhtmlonly "\\htmlonly".
2648 \section cmdendlatexonly \\endlatexonly
2650 \addindex \\endlatexonly
2651 Ends a block of text that was started with a \ref cmdlatexonly "\\latexonly" command.
2653 \sa section \ref cmdlatexonly "\\latexonly".
2656 \section cmdendmanonly \\endmanonly
2658 \addindex \\endmanonly
2659 Ends a block of text that was started with a \ref cmdmanonly "\\manonly" command.
2661 \sa section \ref cmdmanonly "\\manonly".
2664 \section cmdendrtfonly \\endrtfonly
2666 \addindex \\endrtfonly
2667 Ends a block of text that was started with a \ref cmdrtfonly "\\rtfonly" command.
2669 \sa section \ref cmdrtfonly "\\rtfonly".
2673 \section cmdendverbatim \\endverbatim
2675 \addindex \\endverbatim
2676 Ends a block of text that was started with a \ref cmdverbatim "\\verbatim" command.
2678 \sa section \ref cmdverbatim "\\verbatim".
2681 \section cmdendxmlonly \\endxmlonly
2683 \addindex \\endxmlonly
2684 Ends a block of text that was started with a \ref cmdxmlonly "\\xmlonly" command.
2686 \sa section \ref cmdxmlonly "\\xmlonly".
2689 \section cmdfdollar \\f$
2693 Marks the start and end of an in-text formula.
2694 \sa section \ref formulas "formulas" for an example.
2697 \section cmdfbropen \\f[
2701 Marks the start of a long formula that is displayed
2702 centered on a separate line.
2703 \sa section \ref cmdfbrclose "\\f]" and section \ref formulas "formulas".
2706 \section cmdfbrclose \\f]
2710 Marks the end of a long formula that is displayed
2711 centered on a separate line.
2712 \sa section \ref cmdfbropen "\\f[" and section \ref formulas "formulas".
2715 \section cmdfcurlyopen \\f{environment}{
2719 Marks the start of a formula that is in a specific environment.
2720 \note The second \c { is optional and is only to help editors (such as \c Vim) to
2721 do proper syntax highlighting by making the number of opening and closing braces
2723 \sa section \ref cmdfcurlyclose "\\f}" and section \ref formulas "formulas".
2726 \section cmdfcurlyclose \\f}
2730 Marks the end of a formula that is in a specific environment.
2731 \sa section \ref cmdfcurlyopen "\\f{" and section \ref formulas "formulas".
2734 \section cmdhtmlonly \\htmlonly ["[block]"]
2736 \addindex \\htmlonly
2737 Starts a block of text that will be verbatim included in the
2738 generated HTML documentation only. The block ends with a
2739 \ref cmdendhtmlonly "\\endhtmlonly" command.
2741 This command can be used to include HTML code that is too complex
2742 for doxygen (i.e. applets, java-scripts, and HTML tags that
2743 require specific attributes).
2745 Normally the contents between \ref cmdhtmlonly "\\htmlonly" and
2746 \ref cmdendhtmlonly "\\endhtmlonly" is inserted as-is. When you
2747 want to insert a HTML fragment that has block scope like a table or list
2748 which should appear outside \<p\>..\</p\>, this can lead to invalid HTML.
2749 You can use \\htmlonly[block] to make doxygen
2750 end the current paragraph and restart it after \\endhtmlonly.
2752 \note environment variables (like \$(HOME) ) are resolved inside a
2755 \sa section \ref cmdmanonly "\\manonly",
2756 \ref cmdlatexonly "\\latexonly",
2757 \ref cmdrtfonly "\\rtfonly",
2758 \ref cmdxmlonly "\\xmlonly", and
2759 \ref cmddocbookonly "\\docbookonly".
2762 \section cmdimage \\image <format> <file> ["caption"] [<sizeindication>=<size>]
2765 Inserts an image into the documentation. This command is format
2766 specific, so if you want to insert an image for more than one
2767 format you'll have to repeat this command for each format.
2769 The first argument specifies the output format. Currently, the
2770 following values are supported: \c html, \c latex and \c rtf.
2772 The second argument specifies the file name of the image.
2773 doxygen will look for files in the paths (or files) that you specified
2774 after the \ref cfg_image_path "IMAGE_PATH" tag.
2775 If the image is found it will be copied to the correct output directory.
2776 If the image name contains spaces you'll have to put quotes ("...") around it.
2777 You can also specify an absolute URL instead of a file name, but then
2778 doxygen does not copy the image nor check its existence.
2780 The third argument is optional and can be used to specify the caption
2781 that is displayed below the image. This argument has to be specified
2782 on a single line and between quotes even if it does not contain any
2783 spaces. The quotes are stripped before the caption is displayed.
2785 The fourth argument is also optional and can be used to specify the
2786 width or height of the image. This is only useful
2788 (i.e. format=<code>latex</code>). The \c sizeindication can be
2789 either \c width or \c height. The size should be a valid
2790 size specifier in \LaTeX (for example <code>10cm</code> or
2791 <code>6in</code> or a symbolic width like <code>\\textwidth</code>).
2793 Here is example of a comment block:
2796 /*! Here is a snapshot of my new application:
2797 * \image html application.jpg
2798 * \image latex application.eps "My application" width=10cm
2802 And this is an example of how the relevant part of the configuration file
2806 IMAGE_PATH = my_image_dir
2809 \warning The image format for HTML is limited to what your
2810 browser supports. For \LaTeX, the image format
2811 must be Encapsulated PostScript (eps).
2813 Doxygen does not check if the image is in the correct format.
2814 So \e you have to make sure this is the case!
2817 \section cmdlatexonly \\latexonly
2819 \addindex \\latexonly
2820 Starts a block of text that will be verbatim included in the
2821 generated \LaTeX documentation only. The block ends with a
2822 \ref cmdendlatexonly "\\endlatexonly" command.
2824 This command can be used to include \LaTeX code that is too
2825 complex for doxygen (i.e. images, formulas, special characters). You can
2826 use the \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly"
2827 pair to provide a proper HTML alternative.
2830 environment variables (like \$(HOME) ) are resolved inside a
2833 \sa sections \ref cmdrtfonly "\\rtfonly",
2834 \ref cmdxmlonly "\\xmlonly",
2835 \ref cmdmanonly "\\manonly",
2836 \ref cmdhtmlonly "\\htmlonly", and
2837 \ref cmdhtmlonly "\\docbookonly".
2840 \section cmdmanonly \\manonly
2843 Starts a block of text that will be verbatim included in the
2844 generated MAN documentation only. The block ends with a
2845 \ref cmdendmanonly "\\endmanonly" command.
2847 This command can be used to include groff code directly into
2848 MAN pages. You can use the \ref cmdhtmlonly "\\htmlonly" and
2849 \ref cmdendhtmlonly "\\endhtmlonly" and
2850 \ref cmdlatexonly "\\latexonly" and
2851 \ref cmdendlatexonly "\\endlatexonly" pairs to provide proper
2852 HTML and \LaTeX alternatives.
2854 \sa sections \ref cmdhtmlonly "\\htmlonly",
2855 \ref cmdxmlonly "\\xmlonly",
2856 \ref cmdrtfonly "\\rtfonly",
2857 \ref cmdlatexonly "\\latexonly", and
2858 \ref cmddocbookonly "\\docbookonly".
2861 \section cmdli \\li { item-description }
2864 This command has one argument that continues until the first
2865 blank line or until another \c \\li is encountered.
2866 The command can be used to generate a simple, not nested list of
2868 Each argument should start with a \c \\li command.
2873 \li \c AlignLeft left alignment.
2874 \li \c AlignCenter center alignment.
2875 \li \c AlignRight right alignment
2877 No other types of alignment are supported.
2879 will result in the following text:<br><br>
2881 <li> \c AlignLeft left alignment.
2882 <li> \c AlignCenter center alignment.
2883 <li> \c AlignRight right alignment
2885 No other types of alignment are supported.
2888 For nested lists, HTML commands should be used.
2890 Equivalent to \ref cmdarg "\\arg"
2896 Forces a new line. Equivalent to \<br\> and inspired by
2897 the \c printf function.
2900 \section cmdp \\p <word>
2903 Displays the parameter \<word\> using a typewriter font.
2904 You can use this command to refer to member function parameters in
2909 ... the \p x and \p y coordinates are used to ...
2911 This will result in the following text:<br><br>
2912 ... the \p x and \p y coordinates are used to ...
2914 Equivalent to \ref cmdc "\\c"
2915 To have multiple words in typewriter font use \<tt\>multiple words\</tt\>.
2918 \section cmdrtfonly \\rtfonly
2921 Starts a block of text that will be verbatim included in the
2922 generated RTF documentation only. The block ends with a
2923 \ref cmdendrtfonly "\\endrtfonly" command.
2925 This command can be used to include RTF code that is too complex
2929 environment variables (like \$(HOME) ) are resolved inside a
2932 \sa sections \ref cmdmanonly "\\manonly",
2933 \ref cmdxmlonly "\\xmlonly",
2934 \ref cmdlatexonly "\\latexonly",
2935 \ref cmdhtmlonly "\\htmlonly", and
2936 \ref cmddocbookonly "\\docbookonly".
2939 \section cmdverbatim \\verbatim
2941 \addindex \\verbatim
2942 Starts a block of text that will be verbatim included in
2943 the documentation. The block should end with a
2944 \ref cmdendverbatim "\\endverbatim" command.
2945 All commands are disabled in a verbatim block.
2947 \warning Make sure you include a \ref cmdendverbatim "\\endverbatim" command for each
2948 \c \\verbatim command or the parser will get confused!
2950 \sa sections \ref cmdcode "\\code",
2951 \ref cmdendverbatim "\\endverbatim", and
2952 \ref cmdverbinclude "\\verbinclude".
2955 \section cmdxmlonly \\xmlonly
2958 Starts a block of text that will be verbatim included in the
2959 generated XML output only. The block ends with a
2960 \ref cmdendxmlonly "\\endxmlonly" command.
2962 This command can be used to include custom XML tags.
2964 \sa sections \ref cmdmanonly "\\manonly",
2965 \ref cmdrtfonly "\\rtfonly",
2966 \ref cmdlatexonly "\\latexonly",
2967 \ref cmdhtmlonly "\\htmlonly", and
2968 \ref cmddocbookonly "\\docbookonly".
2971 \section cmdbackslash \\\\
2974 This command writes a backslash character (\c \\) to the
2975 output. The backslash has to be escaped in some
2976 cases because doxygen uses it to detect commands.
2982 This command writes an at-sign (\c \@) to the output.
2983 The at-sign has to be escaped in some cases
2984 because doxygen uses it to detect JavaDoc commands.
2987 \section cmdtilde \\~[LanguageId]
2989 This command enables/disables a language specific filter. This can be
2990 used to put documentation for different language into one comment block
2991 and use the \ref cfg_output_language "OUTPUT_LANGUAGE" tag to filter out only a specific language.
2992 Use \c \\~language_id to enable output for a specific language only and
2993 \c \\~ to enable output for all languages (this is also the default mode).
2997 /*! \~english This is English \~dutch Dit is Nederlands \~german Dies ist
2998 Deutsch. \~ output for all languages.
3004 \section cmdamp \\\&
3007 This command writes the \c \& character to the output.
3008 This character has to be escaped because it has a special meaning in HTML.
3011 \section cmddollar \\\$
3014 This command writes the \c \$ character to the output.
3015 This character has to be escaped in some cases, because it is used to expand
3016 environment variables.
3019 \section cmdhash \\\#
3022 This command writes the \c \# character to the output. This
3023 character has to be escaped in some cases, because it is used to refer
3024 to documented entities.
3030 This command writes the \c \< character to the output.
3031 This character has to be escaped because it has a special meaning in HTML.
3037 This command writes the \c \> character to the output. This
3038 character has to be escaped because it has a special meaning in HTML.
3041 \section cmdperc \\\%
3044 This command writes the \c \% character to the output. This
3045 character has to be escaped in some cases, because it is used to
3046 prevent auto-linking to word that is also a documented class or struct.
3049 \section cmdquot \\"
3052 This command writes the \c \" character to the output. This
3053 character has to be escaped in some cases, because it is used in pairs
3054 to indicate an unformatted text fragment.
3057 \section cmdchardot \\.
3060 This command writes a dot (`.`) to the output. This can be useful to
3061 prevent ending a brief description when JAVADOC_AUTOBRIEF is enabled
3062 or to prevent starting a numbered list when the dot follows a number at
3063 the start of a line.
3066 \section cmddcolon \\::
3069 This command writes a double colon (\c \::) to the output. This
3070 character sequence has to be escaped in some cases, because it is used
3071 to reference to documented entities.
3074 \section cmdpipe \\|
3077 This command writes a pipe symbol (\|) to the output. This
3078 character has to be escaped in some cases, because it is used
3079 for Markdown tables.
3082 \section cmdndash \\--
3085 This command writes two dashes (\--) to the output. This allows
3086 writing two consecutive dashes to the output instead of one n-dash character (--).
3089 \section cmdmdash \\---
3092 This command writes three dashes (\---) to the output. This allows
3093 writing three consecutuve dashes to the output instead of one m-dash character (---).
3096 \htmlonly <center> \endhtmlonly
3098 \htmlonly --- \endhtmlonly
3099 Commands included for Qt compatibility
3100 \htmlonly --- \endhtmlonly
3102 \htmlonly </center>\endhtmlonly
3104 The following commands are supported to remain compatible to the Qt class
3105 browser generator. Do \e not use these commands in your own documentation.
3107 <li>\\annotatedclasslist
3108 <li>\\classhierarchy
3112 <li>\\headerfilelist
3121 Go to the <a href="htmlcmds.html">next</a> section or return to the
3122 <a href="index.html">index</a>.