1/****************************************************************************** 2 * 3 * 4 * 5 * Copyright (C) 1997-2015 by Dimitri van Heesch. 6 * 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. 12 * 13 * Documents produced by Doxygen are derivative works derived from the 14 * input used in their production; they are not affected by this license. 15 * 16 */ 17/*! \page commands Special Commands 18 19\section cmd_intro Introduction 20 21All commands in the documentation start with a backslash (<b>\\</b>) or an 22at-sign (<b>\@</b>). If you prefer you can replace all commands starting with a 23backslash below by their counterparts that start with an at-sign. 24 25Some commands have one or more arguments. 26Each argument has a certain range: 27<ul> 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. Note that 33 {curly} braces are also used for command options, here the braces are mandatory 34 and just 'normal' characters. The starting curly brace has to directly follow 35 the command, so without whitespace. 36</ul> 37If in addition to the above argument specifiers [square] brackets are used the argument 38is optional, unless they are placed between quotes in that case they are a mandatory 39part of the command argument. 40 41Here is an alphabetically sorted list of all commands with references to their 42documentation: 43\anchor showsecreflist 44\secreflist 45\refitem cmda \\a 46\refitem cmdaddindex \\addindex 47\refitem cmdaddtogroup \\addtogroup 48\refitem cmdanchor \\anchor 49\refitem cmdarg \\arg 50\refitem cmdattention \\attention 51\refitem cmdauthor \\author 52\refitem cmdauthors \\authors 53\refitem cmdb \\b 54\refitem cmdbrief \\brief 55\refitem cmdbug \\bug 56\refitem cmdc \\c 57\refitem cmdcallergraph \\callergraph 58\refitem cmdcallgraph \\callgraph 59\refitem cmdcategory \\category 60\refitem cmdcite \\cite 61\refitem cmdclass \\class 62\refitem cmdcode \\code 63\refitem cmdconcept \\concept 64\refitem cmdcond \\cond 65\refitem cmdcopybrief \\copybrief 66\refitem cmdcopydetails \\copydetails 67\refitem cmdcopydoc \\copydoc 68\refitem cmdcopyright \\copyright 69\refitem cmddate \\date 70\refitem cmddef \\def 71\refitem cmddefgroup \\defgroup 72\refitem cmddeprecated \\deprecated 73\refitem cmddetails \\details 74\refitem cmddiafile \\diafile 75\refitem cmddir \\dir 76\refitem cmddocbookinclude \\docbookinclude 77\refitem cmddocbookonly \\docbookonly 78\refitem cmddontinclude \\dontinclude 79\refitem cmddot \\dot 80\refitem cmddotfile \\dotfile 81\refitem cmde \\e 82\refitem cmdelse \\else 83\refitem cmdelseif \\elseif 84\refitem cmdem \\em 85\refitem cmdemoji \\emoji 86\refitem cmdendcode \\endcode 87\refitem cmdendcond \\endcond 88\refitem cmdenddocbookonly \\enddocbookonly 89\refitem cmdenddot \\enddot 90\refitem cmdendhtmlonly \\endhtmlonly 91\refitem cmdendif \\endif 92\refitem cmdendinternal \\endinternal 93\refitem cmdendlatexonly \\endlatexonly 94\refitem cmdendlink \\endlink 95\refitem cmdendmanonly \\endmanonly 96\refitem cmdendmsc \\endmsc 97\refitem cmdendparblock \\endparblock 98\refitem cmdendrtfonly \\endrtfonly 99\refitem cmdendsecreflist \\endsecreflist 100\refitem cmdendverbatim \\endverbatim 101\refitem cmdenduml \\enduml 102\refitem cmdendxmlonly \\endxmlonly 103\refitem cmdenum \\enum 104\refitem cmdexample \\example 105\refitem cmdexception \\exception 106\refitem cmdextends \\extends 107\refitem cmdfrndopen \\f( 108\refitem cmdfrndclose \\f) 109\refitem cmdfdollar \\f\$ 110\refitem cmdfbropen \\f[ 111\refitem cmdfbrclose \\f] 112\refitem cmdfcurlyopen \\f{ 113\refitem cmdfcurlyclose \\f} 114\refitem cmdfile \\file 115\refitem cmdfn \\fn 116\refitem cmdheaderfile \\headerfile 117\refitem cmdhidecallergraph \\hidecallergraph 118\refitem cmdhidecallgraph \\hidecallgraph 119\refitem cmdhiderefby \\hiderefby 120\refitem cmdhiderefs \\hiderefs 121\refitem cmdhideinitializer \\hideinitializer 122\refitem cmdhtmlinclude \\htmlinclude 123\refitem cmdhtmlonly \\htmlonly 124\refitem cmdidlexcept \\idlexcept 125\refitem cmdif \\if 126\refitem cmdifnot \\ifnot 127\refitem cmdimage \\image 128\refitem cmdimplements \\implements 129\refitem cmdinclude \\include 130\refitem cmdincludedoc \\includedoc 131\refitem cmdincludelineno \\includelineno 132\refitem cmdingroup \\ingroup 133\refitem cmdinternal \\internal 134\refitem cmdinvariant \\invariant 135\refitem cmdinterface \\interface 136\refitem cmdlatexinclude \\latexinclude 137\refitem cmdlatexonly \\latexonly 138\refitem cmdli \\li 139\refitem cmdline \\line 140\refitem cmdlink \\link 141\refitem cmdmainpage \\mainpage 142\refitem cmdmaninclude \\maninclude 143\refitem cmdmanonly \\manonly 144\refitem cmdmemberof \\memberof 145\refitem cmdmsc \\msc 146\refitem cmdmscfile \\mscfile 147\refitem cmdn \\n 148\refitem cmdname \\name 149\refitem cmdnamespace \\namespace 150\refitem cmdnoop \\noop 151\refitem cmdnosubgrouping \\nosubgrouping 152\refitem cmdnote \\note 153\refitem cmdoverload \\overload 154\refitem cmdp \\p 155\refitem cmdpackage \\package 156\refitem cmdpage \\page 157\refitem cmdpar \\par 158\refitem cmdparagraph \\paragraph 159\refitem cmdparam \\param 160\refitem cmdparblock \\parblock 161\refitem cmdpost \\post 162\refitem cmdpre \\pre 163\refitem cmdprivate \\private 164\refitem cmdprivatesection \\privatesection 165\refitem cmdproperty \\property 166\refitem cmdprotected \\protected 167\refitem cmdprotectedsection \\protectedsection 168\refitem cmdprotocol \\protocol 169\refitem cmdpublic \\public 170\refitem cmdpublicsection \\publicsection 171\refitem cmdpure \\pure 172\refitem cmdraisewarning \\raisewarning 173\refitem cmdref \\ref 174\refitem cmdrefitem \\refitem 175\refitem cmdrelated \\related 176\refitem cmdrelates \\relates 177\refitem cmdrelatedalso \\relatedalso 178\refitem cmdrelatesalso \\relatesalso 179\refitem cmdremark \\remark 180\refitem cmdremarks \\remarks 181\refitem cmdresult \\result 182\refitem cmdreturn \\return 183\refitem cmdreturns \\returns 184\refitem cmdretval \\retval 185\refitem cmdrtfinclude \\rtfinclude 186\refitem cmdrtfonly \\rtfonly 187\refitem cmdsa \\sa 188\refitem cmdsecreflist \\secreflist 189\refitem cmdsection \\section 190\refitem cmdsee \\see 191\refitem cmdshort \\short 192\refitem cmdshowinitializer \\showinitializer 193\refitem cmdshowrefby \\showrefby 194\refitem cmdshowrefs \\showrefs 195\refitem cmdsince \\since 196\refitem cmdskip \\skip 197\refitem cmdskipline \\skipline 198\refitem cmdsnippet \\snippet 199\refitem cmdsnippetdoc \\snippetdoc 200\refitem cmdsnippetlineno \\snippetlineno 201\refitem cmdstatic \\static 202\refitem cmdstartuml \\startuml 203\refitem cmdstruct \\struct 204\refitem cmdsubpage \\subpage 205\refitem cmdsubsection \\subsection 206\refitem cmdsubsubsection \\subsubsection 207\refitem cmdtableofcontents \\tableofcontents 208\refitem cmdtest \\test 209\refitem cmdthrow \\throw 210\refitem cmdthrows \\throws 211\refitem cmdtodo \\todo 212\refitem cmdtparam \\tparam 213\refitem cmdtypedef \\typedef 214\refitem cmdunion \\union 215\refitem cmduntil \\until 216\refitem cmdvar \\var 217\refitem cmdverbatim \\verbatim 218\refitem cmdverbinclude \\verbinclude 219\refitem cmdversion \\version 220\refitem cmdvhdlflow \\vhdlflow 221\refitem cmdwarning \\warning 222\refitem cmdweakgroup \\weakgroup 223\refitem cmdxmlinclude \\xmlinclude 224\refitem cmdxmlonly \\xmlonly 225\refitem cmdxrefitem \\xrefitem 226\refitem cmddollar \\\$ 227\refitem cmdat \\\@ 228\refitem cmdbackslash \\\\ 229\refitem cmdamp \\\& 230\refitem cmdtilde \\~ 231\refitem cmdlt \\\< 232\refitem cmdeq \\= 233\refitem cmdgt \\\> 234\refitem cmdhash \\\# 235\refitem cmdperc \\\% 236\refitem cmdquot \\\" 237\refitem cmdchardot \\\. 238\refitem cmddcolon \:: 239\refitem cmdpipe \\| 240\refitem cmdndash \\\-- 241\refitem cmdmdash \\\--- 242\endsecreflist 243 244The following subsections provide a list of all commands that are recognized by 245doxygen. Unrecognized commands are treated as normal text. 246 247 248\htmlonly</p><center><p>\endhtmlonly 249<h2> 250\htmlonly --- \endhtmlonly 251Structural indicators 252\htmlonly --- \endhtmlonly 253</h2> 254\htmlonly</p></center><p>\endhtmlonly 255 256\section cmdaddtogroup \\addtogroup <name> [(title)] 257 \addindex \\addtogroup 258 Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to 259 that command using the same \<name\> more than once will not result in a warning, 260 but rather one group with a merged documentation and the first title found in 261 any of the commands. 262 263 The title is optional, so this command can also be used to add a number of 264 entities to an existing group using \c \@{ and \c \@} like this: 265 266\verbatim 267 /*! \addtogroup mygrp 268 * Additional documentation for group 'mygrp' 269 * @{ 270 */ 271 272 /*! 273 * A function 274 */ 275 void func1() 276 { 277 } 278 279 /*! Another function */ 280 void func2() 281 { 282 } 283 284 /*! @} */ 285\endverbatim 286 287 \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup", and 288 \ref cmdweakgroup "\\weakgroup". 289 290<hr> 291\section cmdcallgraph \\callgraph 292 293 \addindex \\callgraph 294 When this command is put in a comment block of a function or method 295 and \ref cfg_have_dot "HAVE_DOT" is set to \c YES, then doxygen will 296 generate a call graph for that function (provided the implementation of the 297 function or method calls other documented functions). The call graph will be 298 generated regardless of the value of \ref cfg_call_graph "CALL_GRAPH". 299 \note The completeness (and correctness) of the call graph depends on the 300 doxygen code parser which is not perfect. 301 302 \sa section \ref cmdcallergraph "\\callergraph", 303 section \ref cmdhidecallgraph "\\hidecallgraph", 304 section \ref cmdhidecallergraph "\\hidecallergraph" and 305 option \ref cfg_call_graph "CALL_GRAPH" 306 307<hr> 308\section cmdhidecallgraph \\hidecallgraph 309 310 \addindex \\hidecallgraph 311 When this command is put in a comment block of a function or method 312 and then doxygen will not generate a call graph for that function. The 313 call graph will not be generated regardless of the value of 314 \ref cfg_call_graph "CALL_GRAPH". 315 \note The completeness (and correctness) of the call graph depends on the 316 doxygen code parser which is not perfect. 317 318 \sa section \ref cmdcallergraph "\\callergraph", 319 section \ref cmdcallgraph "\\callgraph", 320 section \ref cmdhidecallergraph "\\hidecallergraph" and 321 option \ref cfg_call_graph "CALL_GRAPH" 322 323<hr> 324\section cmdcallergraph \\callergraph 325 326 \addindex \\callergraph 327 When this command is put in a comment block of a function or method 328 and \ref cfg_have_dot "HAVE_DOT" is set to \c YES, then doxygen will 329 generate a caller graph for that function (provided the implementation of the 330 function or method is called by other documented functions). The caller graph will be 331 generated regardless of the value of \ref cfg_caller_graph "CALLER_GRAPH". 332 \note The completeness (and correctness) of the caller graph depends on the 333 doxygen code parser which is not perfect. 334 335 \sa section \ref cmdcallgraph "\\callgraph", 336 section \ref cmdhidecallgraph "\\hidecallgraph", 337 section \ref cmdhidecallergraph "\\hidecallergraph" and 338 option \ref cfg_caller_graph "CALLER_GRAPH" 339 340<hr> 341\section cmdhidecallergraph \\hidecallergraph 342 343 \addindex \\hidecallergraph 344 When this command is put in a comment block of a function or method 345 and then doxygen will not generate a caller graph for that function. The 346 caller graph will not be generated regardless of the value of 347 \ref cfg_caller_graph "CALLER_GRAPH". 348 \note The completeness (and correctness) of the caller graph depends on the 349 doxygen code parser which is not perfect. 350 351 \sa section \ref cmdcallergraph "\\callergraph", 352 section \ref cmdcallgraph "\\callgraph", 353 section \ref cmdhidecallgraph "\\hidecallgraph" and 354 option \ref cfg_caller_graph "CALLER_GRAPH" 355 356<hr> 357\section cmdshowrefby \\showrefby 358 359 \addindex \\showrefby 360 When this command is put in a comment block of a function, method or variable, 361 then doxygen will generate an overview for that function, method, variable of 362 the, documented, functions and methods that call / use it. 363 The overview will be generated regardless of the value of 364 \ref cfg_referenced_by_relation "REFERENCED_BY_RELATION". 365 \note The completeness (and correctness) of the overview depends on the 366 doxygen code parser which is not perfect. 367 368 \sa section \ref cmdshowrefs "\\showrefs", 369 section \ref cmdhiderefby "\\hiderefby", 370 section \ref cmdhiderefs "\\hiderefs" and 371 option \ref cfg_referenced_by_relation "REFERENCED_BY_RELATION" 372 373<hr> 374\section cmdhiderefby \\hiderefby 375 376 \addindex \\hiderefby 377 When this command is put in a comment block of a function, method or variable 378 then doxygen will not generate an overview for that function, method or 379 variable of the functions and methods that call / use it. 380 The overview will not be generated regardless of the value of 381 \ref cfg_referenced_by_relation "REFERENCED_BY_RELATION". 382 \note The completeness (and correctness) of the overview depends on the 383 doxygen code parser which is not perfect. 384 385 \sa section \ref cmdshowrefs "\\showrefs", 386 section \ref cmdshowrefby "\\showrefby", 387 section \ref cmdhiderefs "\\hiderefs" and 388 option \ref cfg_referenced_by_relation "REFERENCED_BY_RELATION" 389 390<hr> 391\section cmdshowrefs \\showrefs 392 393 \addindex \\showrefs 394 When this command is put in a comment block of a function or method, 395 then doxygen will generate an overview for that function or method of the 396 functions and methods that call it. 397 The overview will be generated regardless of the value of 398 \ref cfg_references_relation "REFERENCES_RELATION". 399 \note The completeness (and correctness) of the overview depends on the 400 doxygen code parser which is not perfect. 401 402 \sa section \ref cmdshowrefby "\\showrefby", 403 section \ref cmdhiderefby "\\hiderefby", 404 section \ref cmdhiderefs "\\hiderefs" and 405 option \ref cfg_references_relation "REFERENCES_RELATION" 406 407<hr> 408\section cmdhiderefs \\hiderefs 409 410 \addindex \\hiderefs 411 When this command is put in a comment block of a function or method 412 and then doxygen will not generate an overview for that function or method of 413 the functions and methods that call it. 414 The overview will not be generated regardless of the value of 415 \ref cfg_references_relation "REFERENCES_RELATION". 416 \note The completeness (and correctness) of the overview depends on the 417 doxygen code parser which is not perfect. 418 419 \sa section \ref cmdshowrefs "\\showrefs", 420 section \ref cmdshowrefby "\\showrefby", 421 section \ref cmdhiderefby "\\hiderefby" and 422 option \ref cfg_references_relation "REFERENCES_RELATION" 423 424<hr> 425\section cmdcategory \\category <name> [<header-file>] [<header-name>] 426 427 \addindex \\category 428 For Objective-C only: Indicates that a comment block contains documentation 429 for a class category with name \<name\>. The arguments are 430 equal to the \ref cmdclass "\\class" command. 431 432 \sa section \ref cmdclass "\\class". 433 434<hr> 435\section cmdclass \\class <name> [<header-file>] [<header-name>] 436 437 \addindex \\class 438 Indicates that a comment block contains documentation for a 439 class with name \<name\>. Optionally a header file and a header name 440 can be specified. If the header-file is specified, a link to a verbatim copy 441 of the header will be included in the HTML documentation. 442 The \<header-name\> argument can be used to overwrite the 443 name of the link that is used in the class documentation to something other 444 than \<header-file\>. This can be useful if the include name is not located 445 on the default include path (like \<X11/X.h\>). With the \<header-name\> 446 argument you can also specify how the include statement should look like, 447 by adding either quotes or sharp brackets around the name. 448 Sharp brackets are used if just the name is given. Note that the 449 last two arguments can also be specified using 450 the \ref cmdheaderfile "\\headerfile" command. 451 452 \par Example: 453 \include class.h 454 \htmlonly 455 Click <a href="examples/class/html/index.html">here</a> 456 for the corresponding HTML documentation that is generated by doxygen. 457 \endhtmlonly 458 \latexonly 459 See \hyperlink{class_example}{Class example} 460 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 461 \endlatexonly 462 463<hr> 464\section cmdconcept \\concept <name> 465 466 \addindex \\concept 467 Indicates that a comment block contains documentation for a 468 C++20 concept with name \<name\>. 469 See also the \ref cmdheaderfile "\\headerfile" command to specify the 470 header a user should be included to use the concept. 471 472<hr> 473\section cmddef \\def <name> 474 475 \addindex \\def 476 Indicates that a comment block contains documentation for a 477 \c \#define macro. 478 479 \par Example: 480 \include define.h 481 \htmlonly 482 Click <a href="examples/define/html/define_8h.html">here</a> 483 for the corresponding HTML documentation that is generated by doxygen. 484 \endhtmlonly 485 \latexonly 486 See \hyperlink{define_8h}{Define example} 487 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 488 \endlatexonly 489 490<hr> 491\section cmddefgroup \\defgroup <name> (group title) 492 493 \addindex \\defgroup 494 Indicates that a comment block contains documentation for a 495 \ref modules "group" of classes, files or namespaces. This can be used to 496 categorize classes, files or namespaces, and document those 497 categories. You can also use groups as members of other groups, 498 thus building a hierarchy of groups. 499 500 The \<name\> argument should be a single-word identifier. 501 502 \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup", and 503 \ref cmdweakgroup "\\weakgroup". 504 505<hr> 506\section cmddir \\dir [<path fragment>] 507 508 \addindex \\dir 509 Indicates that a comment block contains documentation for a directory. 510 The "path fragment" argument should include the directory name and 511 enough of the path to be unique with respect to the other directories 512 in the project. 513 The \ref cfg_strip_from_path "STRIP_FROM_PATH" option determines what is 514 stripped from the full path before it appears in the output. 515 516<hr> 517\section cmdenum \\enum <name> 518 519 \addindex \\enum 520 Indicates that a comment block contains documentation for an 521 enumeration, with name \<name\>. If the enum is a member of a class and 522 the documentation block is located outside the class definition, 523 the scope of the class should be specified as well. 524 If a comment block is located directly in front of an enum declaration, 525 the \c \\enum comment may be omitted. 526 527 \par Note: 528 The type of an anonymous enum cannot be documented, but the values 529 of an anonymous enum can. 530 531 \par Example: 532 \include enum.h 533 \htmlonly 534 Click <a href="examples/enum/html/class_enum___test.html">here</a> 535 for the corresponding HTML documentation that is generated by doxygen. 536 \endhtmlonly 537 \latexonly 538 See \hyperlink{class_enum___test}{Enum example} 539 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 540 \endlatexonly 541 542<hr> 543\section cmdexample \\example['{lineno}'] <file-name> 544 545 \addindex \\example 546 Indicates that a comment block contains documentation for a source code 547 example. The name of the source file is \<file-name\>. 548 The contents of this file will be included in the documentation, just after the 549 documentation contained in the comment block. 550 You can add option `{lineno}` to enable line numbers for the example if desired. 551 All examples are placed in a list. The source code is scanned for documented members and classes. 552 If any are found, the names are cross-referenced with the documentation. 553 Source files or directories can be specified using the 554 \ref cfg_example_path "EXAMPLE_PATH" 555 tag of doxygen's configuration file. 556 557 If \<file-name\> itself is not unique for the set of example files specified 558 by the 559 \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part of the absolute path 560 to disambiguate it. 561 562 If more than one source file is needed for the example, 563 the \ref cmdinclude "\\include" command can be used. 564 565 \par Example: 566 \include example.cpp 567 Where the example file \c example_test.cpp looks as follows: 568 \include example_test.cpp 569 \htmlonly 570 Click <a href="examples/example/html/examples.html">here</a> 571 for the corresponding HTML documentation that is generated by doxygen. 572 \endhtmlonly 573 \latexonly 574 See \hyperlink{example_test_8cpp-example}{Example example} 575 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 576 \endlatexonly 577 578 \sa section \ref cmdinclude "\\include". 579 580<hr> 581\section cmdendinternal \\endinternal 582 583 \addindex \\endinternal 584 This command ends a documentation fragment that was started with a 585 \ref cmdinternal "\\internal" command. The text between \ref cmdinternal "\\internal" and 586 \c \\endinternal will only be visible 587 if \ref cfg_internal_docs "INTERNAL_DOCS" is set to \c YES. 588 589<hr> 590\section cmdextends \\extends <name> 591 592 \addindex \\extends 593 This command can be used to manually indicate an inheritance relation, 594 when the programming language does not support this concept natively 595 (e.g. C). 596 597 The file \c manual.c in the example directory shows how to use this command. 598 599 \htmlonly 600 Click <a href="examples/manual/html/index.html">here</a> 601 for the corresponding HTML documentation that is generated by doxygen. 602 \endhtmlonly 603 \latexonly 604 See \hyperlink{extends_example}{Extends example} 605 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 606 \endlatexonly 607 608 \sa section \ref cmdimplements "\\implements" and section 609 \ref cmdmemberof "\\memberof" 610 611<hr> 612\section cmdfile \\file [<name>] 613 614 \addindex \\file 615 Indicates that a comment block contains documentation for a source or 616 header file with name \<name\>. The file name may include (part of) the 617 path if the file-name alone is not unique. If the file name is omitted 618 (i.e. the line after \c \\file is left blank) then the documentation block that 619 contains the \c \\file command will belong to the file it is located in. 620 621 \par Important: 622 The documentation of global functions, variables, typedefs, and enums will 623 only be included in the output if the file they are in is documented as well 624 or if \ref cfg_extract_all "EXTRACT_ALL" is set to \c YES. 625 626 \par Example: 627 \include file.h 628 \htmlonly 629 Click <a href="examples/file/html/file_8h.html">here</a> 630 for the corresponding HTML documentation that is generated by doxygen. 631 \endhtmlonly 632 \latexonly 633 See \hyperlink{file_example}{File example} 634 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 635 \endlatexonly 636 637 \note In the above example \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" 638 has been set to \c YES in the configuration file. 639 640<hr> 641\section cmdfn \\fn (function declaration) 642 643 \addindex \\fn 644 Indicates that a comment block contains documentation for a function 645 (either global or as a member of a class). This command is \em only 646 needed if a comment block is \e not placed in front (or behind) 647 the function declaration or definition. 648 649 If your comment block \e is in front of the function 650 declaration or definition this command can (and to avoid redundancy 651 should) be omitted. 652 653 A full function declaration including arguments should be specified after the 654 \c \\fn command on a \e single line, since the argument ends at the end 655 of the line! 656 657 This command is equivalent to \ref cmdvar "\\var", \ref cmdtypedef "\\typedef", 658 and \ref cmdproperty "\\property". 659 660 \warning Do not use this command 661 if it is not absolutely needed, since it will lead to duplication of 662 information and thus to errors. 663 664 \par Example: 665 \include func.h 666 \htmlonly 667 Click <a href="examples/func/html/class_fn___test.html">here</a> 668 for the corresponding HTML documentation that is generated by doxygen. 669 \endhtmlonly 670 \latexonly 671 See \hyperlink{class_fn___test}{Fn example} 672 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 673 \endlatexonly 674 675 \sa sections \ref cmdvar "\\var", \ref cmdproperty "\\property", and 676 \ref cmdtypedef "\\typedef". 677 678<hr> 679\section cmdheaderfile \\headerfile <header-file> [<header-name>] 680 681 \addindex \\headerfile 682 Intended to be used for class, struct, or union documentation, where 683 the documentation is in front of the definition. The arguments of 684 this command are the same as the second and third argument of 685 \ref cmdclass "\\class". 686 The \<header-file\> name refers to the file that should be included by the 687 application to obtain the definition of the class, struct, or union. 688 The \<header-name\> argument can be used to overwrite the 689 name of the link that is used in the class documentation to something other 690 than \<header-file\>. This can be useful if the include name is not located 691 on the default include path (like \<X11/X.h\>). 692 693 With the \<header-name\> 694 argument you can also specify how the include statement should look like, 695 by adding either double quotes or sharp brackets around the name. 696 By default sharp brackets are used if just the name is given. 697 698 If a pair of double quotes is given for either the \<header-file\> or 699 \<header-name\> argument, the current file (in which the command was found) 700 will be used but with quotes. So for a comment block with a \c \\headerfile 701 command inside a file <code>test.h</code>, the following three commands are equivalent: 702 \verbatim 703 \headerfile test.h "test.h" 704 \headerfile test.h "" 705 \headerfile "" \endverbatim 706 To get sharp brackets you do not need to specify anything, 707 but if you want to be explicit you could use any of the following: 708 \verbatim 709 \headerfile test.h <test.h> 710 \headerfile test.h <> 711 \headerfile <> \endverbatim 712 713 To globally reverse the default include representation to 714 local includes you can set 715 \ref cfg_force_local_includes "FORCE_LOCAL_INCLUDES" to \c YES. 716 717 To disable the include information altogether set 718 \ref cfg_show_headerfile "SHOW_HEADERFILE" to \c NO. 719 720<hr> 721\section cmdhideinitializer \\hideinitializer 722 723 \addindex \\hideinitializer 724 By default the value of a define and the initializer of a variable 725 are displayed unless they are longer than 30 lines. By putting 726 this command in a comment block of a define or variable, the 727 initializer is always hidden. The maximum number of initialization lines 728 can be changed by means of the configuration parameter 729 \ref cfg_max_initializer_lines "MAX_INITIALIZER_LINES", the default 730 value is 30. 731 732 \sa section \ref cmdshowinitializer "\\showinitializer". 733 734<hr> 735\section cmdidlexcept \\idlexcept <name> 736 \addindex \\idlexcept 737 738 Indicates that a comment block contains documentation for a 739 IDL exception with name \<name\>. 740 741<hr> 742\section cmdimplements \\implements <name> 743 744 \addindex \\implements 745 This command can be used to manually indicate an inheritance relation, 746 when the programming language does not support this concept natively 747 (e.g. C). 748 749 The file \c manual.c in the example directory shows how to use this command. 750 751 \htmlonly 752 Click <a href="examples/manual/html/index.html">here</a> 753 for the corresponding HTML documentation that is generated by doxygen. 754 \endhtmlonly 755 \latexonly 756 See \hyperlink{extends_example}{Implements example} 757 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 758 \endlatexonly 759 760 \sa section \ref cmdextends "\\extends" and section 761 \ref cmdmemberof "\\memberof" 762 763<hr> 764\section cmdingroup \\ingroup (<groupname> [<groupname> <groupname>]) 765 766 \addindex \\ingroup 767 If the \c \\ingroup command is placed in a comment block of a 768 class, file or namespace, then it will be added to the group or 769 groups identified by \<groupname\>. 770 771 \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", 772 \ref cmdaddtogroup "\\addtogroup", and \ref cmdweakgroup "\\weakgroup" 773 774<hr> 775\section cmdinterface \\interface <name> [<header-file>] [<header-name>] 776 777 \addindex \\interface 778 Indicates that a comment block contains documentation for an 779 interface with name \<name\>. The arguments are equal to the arguments of the 780 \ref cmdclass "\\class" command. 781 782 \sa section \ref cmdclass "\\class". 783 784<hr> 785\section cmdinternal \\internal 786 787 \addindex \\internal 788 This command starts a documentation fragment that is meant for internal 789 use only. The fragment naturally ends at the end of the comment block. 790 You can also force the internal section to end earlier by using the 791 \ref cmdendinternal "\\endinternal" command. 792 793 If the \c \\internal command is put inside a section 794 (see for example \ref cmdsection "\\section") all subsections after the 795 command are considered to be internal as well. Only a new section at the 796 same level will end the fragment that is considered internal. 797 798 You can use \ref cfg_internal_docs "INTERNAL_DOCS" in the configuration file 799 to show (\c YES) or hide (\c NO) the internal documentation. 800 801 \sa section \ref cmdendinternal "\\endinternal". 802 803 804<hr> 805\section cmdmainpage \\mainpage [(title)] 806 807 \addindex \\mainpage 808 809 If the \c \\mainpage command is placed in a comment block the 810 block is used to customize the index page (in HTML) or 811 the first chapter (in \LaTeX). 812 813 The title argument is optional and replaces the default title that 814 doxygen normally generates. If you do not want any title you can 815 specify \c notitle as the argument of \c \\mainpage. 816 817 Here is an example: 818\verbatim 819/*! \mainpage My Personal Index Page 820 * 821 * \section intro_sec Introduction 822 * 823 * This is the introduction. 824 * 825 * \section install_sec Installation 826 * 827 * \subsection step1 Step 1: Opening the box 828 * 829 * etc... 830 */ 831\endverbatim 832 833 You can refer to the main page using: <code>\ref cmdref "\\ref" index</code>. 834 835 \sa section \ref cmdsection "\\section", 836 section \ref cmdsubsection "\\subsection", and 837 section \ref cmdpage "\\page". 838 839<hr> 840\section cmdmemberof \\memberof <name> 841 842 \addindex \\memberof 843 This command makes a function a member of a class in a similar way 844 as \ref cmdrelates "\\relates" does, only with this command the function 845 is represented as a real member of the class. 846 This can be useful when the programming language does not support 847 the concept of member functions natively (e.g. C). 848 849 It is also possible to use this command together with 850 \ref cmdpublic "\\public", \ref cmdprotected "\\protected" or 851 \ref cmdprivate "\\private". 852 853 The file \c manual.c in the example directory shows how to use this command. 854 855 \htmlonly 856 Click <a href="examples/manual/html/index.html">here</a> 857 for the corresponding HTML documentation that is generated by doxygen. 858 \endhtmlonly 859 860 \sa sections \ref cmdextends "\\extends", \ref cmdimplements "\\implements", 861 \ref cmdpublic "\\public", \ref cmdprotected "\\protected" and 862 \ref cmdprivate "\\private". 863 864<hr> 865\section cmdname \\name [(header)] 866 867 \addindex \\name 868 869 This command turns a comment block into a header 870 definition of a member group. The 871 comment block should be followed by a 872 <code>///\@{ ... ///\@}</code> block containing the 873 members of the group. 874 875 See section \ref memgroup for an example. 876 877<hr> 878\section cmdnamespace \\namespace <name> 879 880 \addindex \\namespace 881 Indicates that a comment block contains documentation for a 882 namespace with name \<name\>. 883 884<hr> 885\section cmdnosubgrouping \\nosubgrouping 886 887 \addindex \\nosubgrouping 888 This command can be put in the documentation 889 of a class. It can be used in combination with member grouping 890 to avoid that doxygen puts a member group as a subgroup of a 891 Public/Protected/Private/... section. 892 893 \sa sections \ref cmdpublicsection "\\publicsection", 894 \ref cmdprotectedsection "\\protectedsection" and 895 \ref cmdprivatesection "\\privatesection". 896 897<hr> 898\section cmdoverload \\overload [(function declaration)] 899 900 \addindex \\overload 901 This command can be used to generate the following 902 standard text for an overloaded member function: 903 904 > This is an overloaded member function, provided for convenience. 905 > It differs from the above function only in what argument(s) it accepts. 906 907 If the documentation for the overloaded member function is not located 908 in front of the function declaration or definition, the optional 909 argument should be used to specify the correct function. 910 911 Any other documentation that is inside the documentation block will 912 by appended after the generated message. 913 914 \par Note 1: 915 You are responsible that there is indeed an 916 earlier documented member that is overloaded by this one. 917 To prevent that document reorders the documentation you should set 918 \ref cfg_sort_member_docs "SORT_MEMBER_DOCS" to \c NO in this case. 919 \par Note 2: 920 The \c \\overload command does not work inside a one-line comment. 921 \par Example: 922 \include overload.cpp 923 \htmlonly 924 Click <a href="examples/overload/html/class_overload___test.html">here</a> 925 for the corresponding HTML documentation that is generated by doxygen. 926 \endhtmlonly 927 \latexonly 928 See \hyperlink{class_overload___test}{Overload example} 929 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 930 \endlatexonly 931 932<hr> 933\section cmdpackage \\package <name> 934 935 \addindex \\package 936 Indicates that a comment block contains documentation for a 937 Java package with name \<name\>. 938 939<hr> 940\section cmdpage \\page <name> (title) 941 942 \addindex \\page 943 Indicates that a comment block contains a piece of documentation that is 944 not directly related to one specific class, file or member. 945 The HTML generator creates a page containing the documentation. The 946 \LaTeX generator 947 starts a new section in the chapter 'Page documentation'. 948 949 \par Example: 950 \include page.doc 951 \htmlonly 952 Click <a href="examples/page/html/pages.html">here</a> 953 for the corresponding HTML documentation that is generated by doxygen. 954 \endhtmlonly 955 \latexonly 956 See \hyperlink{page_example}{Page example} 957 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 958 \endlatexonly 959 960 \par Note: 961 The \<name\> argument consists of a combination of letters and number 962 digits. If you wish to use upper case letters (e.g. \c MYPAGE1), or 963 mixed case letters (e.g. \c MyPage1) in the \<name\> argument, you 964 should set \ref cfg_case_sense_names "CASE_SENSE_NAMES" to \c YES. However, this is advisable 965 only if your file system is case sensitive. Otherwise (and for better 966 portability) you should use all lower case letters (e.g. \c mypage1) 967 for \<name\> in all references to the page. 968 969 \sa section \ref cmdsection "\\section", section 970 \ref cmdsubsection "\\subsection", and section 971 \ref cmdref "\\ref". 972 973<hr> 974\section cmdprivate \\private 975 976 \addindex \\private 977 Indicates that the member documented by the comment block is private, 978 i.e., should only be accessed by other members in the same class. 979 980 Note that doxygen automatically detects the protection level of members 981 in object-oriented languages. This command is intended for use only when 982 the language does not support the concept of protection level natively 983 (e.g. C, PHP 4). 984 985 For starting a section of private members, in a way similar to the 986 "private:" class marker in C++, use \ref cmdprivatesection "\\privatesection". 987 988 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public", 989 \ref cmdprotected "\\protected" and \ref cmdprivatesection "\\privatesection". 990 991<hr> 992\section cmdprivatesection \\privatesection 993 994 \addindex \\privatesection 995 Starting a section of private members, in a way similar to the 996 "private:" class marker in C++. 997 Indicates that the member documented by the comment block is private, 998 i.e., should only be accessed by other members in the same class. 999 1000 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public", 1001 \ref cmdprotected "\\protected" and \ref cmdprivate "\\private". 1002 1003<hr> 1004\section cmdproperty \\property (qualified property name) 1005 1006 \addindex \\property 1007 Indicates that a comment block contains documentation for a 1008 property (either global or as a member of a class). 1009 This command is equivalent to \ref cmdfn "\\fn", 1010 \ref cmdtypedef "\\typedef", and \ref cmdvar "\\var". 1011 1012 \sa sections \ref cmdfn "\\fn", \ref cmdtypedef "\\typedef", and 1013 \ref cmdvar "\\var". 1014 1015<hr> 1016\section cmdprotected \\protected 1017 1018 \addindex \\protected 1019 Indicates that the member documented by the comment block is protected, 1020 i.e., should only be accessed by other members in the same or derived 1021 classes. 1022 1023 Note that doxygen automatically detects the protection level of members 1024 in object-oriented languages. This command is intended for use only when 1025 the language does not support the concept of protection level natively 1026 (e.g. C, PHP 4). 1027 1028 For starting a section of protected members, in a way similar to the 1029 "protected:" class marker in C++, use \ref cmdprotectedsection "\\protectedsection". 1030 1031 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public", 1032 \ref cmdprivate "\\private" and \ref cmdprotectedsection "\\protectedsection". 1033 1034<hr> 1035\section cmdprotectedsection \\protectedsection 1036 1037 \addindex \\protectedsection 1038 Starting a section of protected members, in a way similar to the 1039 "protected:" class marker in C++. 1040 Indicates that the member documented by the comment block is protected, 1041 i.e., should only be accessed by other members in the same or derived 1042 classes. 1043 1044 \sa sections \ref cmdmemberof "\\memberof", \ref cmdpublic "\\public", 1045 \ref cmdprivate "\\private" and \ref cmdprotected "\\protected". 1046 1047<hr> 1048\section cmdprotocol \\protocol <name> [<header-file>] [<header-name>] 1049 1050 \addindex \\protocol 1051 Indicates that a comment block contains documentation for a 1052 protocol in Objective-C with name \<name\>. The arguments are equal 1053 to the \ref cmdclass "\\class" command. 1054 1055 \sa section \ref cmdclass "\\class". 1056 1057<hr> 1058\section cmdpublic \\public 1059 1060 \addindex \\public 1061 Indicates that the member documented by the comment block is public, 1062 i.e., can be accessed by any other class or function. 1063 1064 Note that doxygen automatically detects the protection level of members 1065 in object-oriented languages. This command is intended for use only when 1066 the language does not support the concept of protection level natively 1067 (e.g. C, PHP 4). 1068 1069 For starting a section of public members, in a way similar to the 1070 "public:" class marker in C++, use \ref cmdpublicsection "\\publicsection". 1071 1072 \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected", 1073 \ref cmdprivate "\\private" and \ref cmdpublicsection "\\publicsection". 1074 1075<hr> 1076\section cmdpublicsection \\publicsection 1077 1078 \addindex \\publicsection 1079 Starting a section of public members, in a way similar to the 1080 "public:" class marker in C++. 1081 Indicates that the member documented by the comment block is public, 1082 i.e., can be accessed by any other class or function. 1083 1084 \sa sections \ref cmdmemberof "\\memberof", \ref cmdprotected "\\protected", 1085 \ref cmdprivate "\\private" and \ref cmdpublic "\\public". 1086 1087<hr> 1088\section cmdpure \\pure 1089 1090 \addindex \\pure 1091 Indicates that the member documented by the comment block is pure virtual, 1092 i.e., it is abstract and has no implementation associated with it. 1093 1094 This command is intended for use only when 1095 the language does not support the concept of pure virtual methods natively 1096 (e.g. C, PHP 4). 1097 1098<hr> 1099\section cmdrelates \\relates <name> 1100 1101 \addindex \\relates 1102 This command can be used in the documentation of a non-member function 1103 \<name\>. It puts the function inside the 'related function' section 1104 of the class documentation. This command is useful for documenting 1105 non-friend functions that are nevertheless strongly coupled to a certain 1106 class. It prevents the need of having to document a file, but 1107 only works for functions. 1108 1109 \par Example: 1110 \include relates.cpp 1111 \htmlonly 1112 Click <a href="examples/relates/html/class_string.html">here</a> 1113 for the corresponding HTML documentation that is generated by doxygen. 1114 \endhtmlonly 1115 \latexonly 1116 See \hyperlink{class_string}{Relates example} 1117 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 1118 \endlatexonly 1119 1120<hr> 1121\section cmdrelated \\related <name> 1122 1123 \addindex \\related 1124 Equivalent to \ref cmdrelates "\\relates" 1125 1126<hr> 1127\section cmdrelatesalso \\relatesalso <name> 1128 1129 \addindex \\relatesalso 1130 This command can be used in the documentation of a non-member function 1131 \<name\>. It puts the function both inside the 'related function' section 1132 of the class documentation as well as leaving it at its normal file documentation 1133 location. This command is useful for documenting 1134 non-friend functions that are nevertheless strongly coupled to a certain 1135 class. It only works for functions. 1136 1137<hr> 1138\section cmdrelatedalso \\relatedalso <name> 1139 1140 \addindex \\relatedalso 1141 Equivalent to \ref cmdrelatesalso "\\relatesalso" 1142 1143<hr> 1144\section cmdshowinitializer \\showinitializer 1145 1146 \addindex \\showinitializer 1147 By default the value of a define and the initializer of a variable 1148 are only displayed if they are less than 30 lines long. By putting 1149 this command in a comment block of a define or variable, the 1150 initializer is shown unconditionally. 1151 The maximum number of initialization lines 1152 can be changed by means of the configuration parameter 1153 \ref cfg_max_initializer_lines "MAX_INITIALIZER_LINES", the default value is 1154 30. 1155 1156 \sa section \ref cmdhideinitializer "\\hideinitializer". 1157 1158<hr> 1159\section cmdstatic \\static 1160 1161 \addindex \\static 1162 Indicates that the member documented by the comment block is static, 1163 i.e., it works on a class, instead of on an instance of the class. 1164 1165 This command is intended for use only when 1166 the language does not support the concept of static methods natively (e.g. C). 1167 1168<hr> 1169\section cmdstruct \\struct <name> [<header-file>] [<header-name>] 1170 1171 \addindex \\struct 1172 Indicates that a comment block contains documentation for a 1173 struct with name \<name\>. The arguments are equal to the arguments of the 1174 \ref cmdclass "\\class" command. 1175 1176 \sa section \ref cmdclass "\\class". 1177 1178<hr> 1179\section cmdtypedef \\typedef (typedef declaration) 1180 1181 \addindex \\typedef 1182 Indicates that a comment block contains documentation for a 1183 typedef (either global or as a member of a class). 1184 This command is equivalent to \ref cmdfn "\\fn", 1185 \ref cmdproperty "\\property", and \ref cmdvar "\\var". 1186 1187 \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and 1188 \ref cmdvar "\\var". 1189 1190<hr> 1191\section cmdunion \\union <name> [<header-file>] [<header-name>] 1192 1193 \addindex \\union 1194 Indicates that a comment block contains documentation for a 1195 union with name \<name\>. The arguments are equal to the arguments of the 1196 \ref cmdclass "\\class" command. 1197 1198 \sa section \ref cmdclass "\\class". 1199 1200<hr> 1201\section cmdvar \\var (variable declaration) 1202 1203 \addindex \\var 1204 Indicates that a comment block contains documentation for a variable or 1205 enum value (either global or as a member of a class). 1206 This command is equivalent to \ref cmdfn "\\fn", 1207 \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef". 1208 1209 Note that for PHP one can also specify the type of the variable. 1210 The syntax is similar as for the `phpDocumentor` but the description has to start 1211 at the next line, i.e. 1212\verbatim 1213@var datatype $varname 1214Description 1215\endverbatim 1216 1217 \sa section \ref cmdfn "\\fn", \ref cmdproperty "\\property", and \ref cmdtypedef "\\typedef". 1218 1219<hr> 1220\section cmdvhdlflow \\vhdlflow [(title for the flow chart)] 1221 1222 \addindex \\vhdlflow 1223 This is a VHDL specific command, which can be put in the documentation of a process to 1224 produce a flow chart of the logic in the process. 1225 Optionally a title for the flow chart can be given. 1226 \note Currently the flow chart will only appear in the HTML output. 1227 1228<hr> 1229\section cmdweakgroup \\weakgroup <name> [(title)] 1230 \addindex \\weakgroup 1231 Can be used exactly like \ref cmdaddtogroup "\\addtogroup", but has 1232 a lower priority when it comes to resolving conflicting grouping 1233 definitions. 1234 1235 \sa page \ref grouping "Grouping" and section \ref cmdaddtogroup "\\addtogroup". 1236 1237<hr> 1238 1239\htmlonly</p><center><p>\endhtmlonly 1240<h2> 1241\htmlonly --- \endhtmlonly 1242Section indicators 1243\htmlonly --- \endhtmlonly 1244</h2> 1245\htmlonly</p></center><p>\endhtmlonly 1246 1247<hr> 1248\section cmdattention \\attention { attention text } 1249 1250 \addindex \\attention 1251 Starts a paragraph where a message that needs attention may be entered. 1252 The paragraph will be indented. 1253 The text of the paragraph has no special internal structure. All visual 1254 enhancement commands may be used inside the paragraph. 1255 Multiple adjacent \c \\attention commands will be joined into a single paragraph. 1256 The \c \\attention command ends when a blank line or some other 1257 sectioning command is encountered. 1258 1259<hr> 1260\section cmdauthor \\author { list of authors } 1261 1262 \addindex \\author 1263 Starts a paragraph where one or more author names may be entered. 1264 The paragraph will be indented. 1265 The text of the paragraph has no special internal structure. All visual 1266 enhancement commands may be used inside the paragraph. 1267 Multiple adjacent \c \\author commands will be joined into a single paragraph. 1268 Each author description will start a new line. Alternatively, one \c \\author command 1269 may mention several authors. The \c \\author command ends when a blank line or some other 1270 sectioning command is encountered. 1271 1272 \par Example: 1273 \include author.cpp 1274 \htmlonly 1275 Click <a href="examples/author/html/class_some_nice_class.html">here</a> 1276 for the corresponding HTML documentation that is generated by doxygen. 1277 \endhtmlonly 1278 \latexonly 1279 See \hyperlink{class_some_nice_class}{Author example} 1280 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 1281 \endlatexonly 1282 1283<hr> 1284\section cmdauthors \\authors { list of authors } 1285 1286 \addindex \\authors 1287 Equivalent to \ref cmdauthor "\\author". 1288 1289<hr> 1290\section cmdbrief \\brief { brief description } 1291 1292 \addindex \\brief 1293 Starts a paragraph that serves as a brief description. For classes and files 1294 the brief description will be used in lists and at the start of the 1295 documentation page. For class and file members, the brief description 1296 will be placed at the declaration of the member and prepended to the 1297 detailed description. A brief description may span several lines (although 1298 it is advised to keep it brief!). A brief description ends when a 1299 blank line or another sectioning command is encountered. If multiple 1300 \c \\brief commands are present they will be joined. See section 1301 \ref cmdauthor "\\author" for an example. 1302 1303 Synonymous to \ref cmdshort "\\short". 1304 1305<hr> 1306\section cmdbug \\bug { bug description } 1307 1308 \addindex \\bug 1309 Starts a paragraph where one or more bugs may be reported. 1310 The paragraph will be indented. 1311 The text of the paragraph has no special internal structure. All visual 1312 enhancement commands may be used inside the paragraph. 1313 Multiple adjacent \c \\bug commands will be joined into a single paragraph. 1314 Each bug description will start on a new line. 1315 Alternatively, one \c \\bug command may mention 1316 several bugs. The \c \\bug command ends when a blank line or some other 1317 sectioning command is encountered. See section \ref cmdauthor "\\author" 1318 for an example. 1319 1320<hr> 1321\section cmdcond \\cond [(section-label)] 1322 1323 \addindex \\cond 1324 Starts a conditional section that ends with a corresponding 1325 \ref cmdendcond "\\endcond" command, which is typically found in 1326 another comment block. The main purpose of this pair of 1327 commands is to (conditionally) exclude part of a file from processing 1328 (in older version of doxygen this could only be achieved using C preprocessor commands). 1329 1330 The section between \c \\cond and \ref cmdendcond "\\endcond" can be included by 1331 adding its section label to the \ref cfg_enabled_sections "ENABLED_SECTIONS" 1332 configuration option. If the section label is omitted, the section will 1333 be excluded from processing unconditionally. The section label can be a 1334 logical expression build of section labels, round brackets, && (AND), || (OR) and ! (NOT). 1335 If you use an expression you need to wrap it in round brackets, i.e 1336 <tt>\\cond (!LABEL1 && LABEL2)</tt>. 1337 1338 For conditional sections within a comment block one should 1339 use a \ref cmdif "\\if" ... \ref cmdendif "\\endif" block. 1340 When using \c \\cond and the condition is not satisfied the current comment block is 1341 ended and everything until the matching \ref cmdendcond "\\endcond" is removed 1342 and a new command block is started there. 1343 1344 Conditional sections can be nested. In this case a nested section will only 1345 be shown if it and its containing section are included. 1346 1347 Here is an example showing the commands in action: 1348 1349\verbatim 1350/** An interface */ 1351class Intf 1352{ 1353 public: 1354 /** A method */ 1355 virtual void func() = 0; 1356 1357 /// @cond TEST 1358 1359 /** A method used for testing */ 1360 virtual void test() = 0; 1361 1362 /// @endcond 1363}; 1364 1365/// @cond DEV 1366/* 1367 * The implementation of the interface 1368 */ 1369class Implementation : public Intf 1370{ 1371 public: 1372 void func(); 1373 1374 /// @cond TEST 1375 void test(); 1376 /// @endcond 1377 1378 /// @cond 1379 /** This method is obsolete and does 1380 * not show up in the documentation. 1381 */ 1382 void obsolete(); 1383 /// @endcond 1384}; 1385 1386/// @endcond 1387\endverbatim 1388 1389The output will be different depending on whether or not \ref cfg_enabled_sections "ENABLED_SECTIONS" 1390contains \c TEST, or \c DEV 1391 1392 \sa sections \ref cmdif "\\if", \ref cmdifnot "\\ifnot", 1393 \ref cmdelse "\\else", \ref cmdelseif "\\elseif", 1394 \ref cmdendif "\\endif", \ref cmdendcond "\\endcond", and 1395 \ref cfg_enabled_sections "ENABLED_SECTIONS". 1396 \note Due to the moment of parsing the \c \\cond and \ref cmdendcond "\\endcond" commands cannot 1397 be used in \ref cfg_aliases "ALIASES". 1398 1399<hr> 1400\section cmdcopyright \\copyright { copyright description } 1401 1402 \addindex \\copyright 1403 Starts a paragraph where the copyright of an entity can be described. 1404 This paragraph will be indented. 1405 The text of the paragraph has no special internal structure. 1406 See section \ref cmdauthor "\\author" for an example. 1407 1408<hr> 1409\section cmddate \\date { date description } 1410 1411 \addindex \\date 1412 Starts a paragraph where one or more dates may be entered. 1413 The paragraph will be indented. 1414 The text of the paragraph has no special internal structure. All visual 1415 enhancement commands may be used inside the paragraph. 1416 Multiple adjacent \c \\date commands will be joined into a single paragraph. 1417 Each date description will start on a new line. 1418 Alternatively, one \c \\date command may mention 1419 several dates. The \c \\date command ends when a blank line or some other 1420 sectioning command is encountered. See section \ref cmdauthor "\\author" 1421 for an example. 1422 1423<hr> 1424\section cmddeprecated \\deprecated { description } 1425 1426 \addindex \\deprecated 1427 Starts a paragraph indicating that this documentation block belongs to 1428 a deprecated entity. Can be used to describe alternatives, 1429 expected life span, etc. 1430 1431<hr> 1432\section cmddetails \\details { detailed description } 1433 1434 \addindex \\details 1435 Just like \ref cmdbrief "\\brief" starts a brief description, \c \\details 1436 starts the detailed description. You can also start a new paragraph (blank line) 1437 then the \c \\details command is not needed. 1438 1439<hr> 1440\section cmdnoop \\noop ( text to be ignored ) 1441 1442 \addindex \\noop 1443 All the text, including the command, till the end of the line is ignored. 1444 The command will most commonly be used in combination with \ref cfg_aliases "ALIASES" 1445 to ignore not supported commands that are present for e.g. other processing tools. 1446<hr> 1447\section cmdraisewarning \\raisewarning ( text to be shown as warning ) 1448 1449 \addindex \\raisewarning 1450 All the text, excluding the command, till the end of the line is is literally shown 1451 as a documentation warning. The text, including the command, is removed from the output. 1452 The command will most commonly be used in combination with \ref cfg_aliases "ALIASES" 1453 to show a specific warning. 1454 \par Example: 1455\verbatim 1456\raisewarning My specific warnning 1457 1458\warnNoDoc 1459 1460\warnNoDoc{My specific warnning} 1461\endverbatim 1462 together with: 1463\verbatim 1464ALIASES = warnNoDoc="\raisewarning Missing documentation" 1465ALIASES += warnNoDoc{1}="\raisewarning Incomplete documentation: \1" 1466\endverbatim 1467 will result in: 1468\verbatim 1469 ex_1.md:1: warning: My specific warnning 1470 ex_1.md:3: warning: Missing documentation 1471 ex_1.md:5: warning: Incomplete documentation: My specific warnning 1472\endverbatim 1473 1474<hr> 1475\section cmdelse \\else 1476 1477 \addindex \\else 1478 Starts a conditional section if the previous conditional section 1479 was not enabled. The previous section should have been started with 1480 a \ref cmdif "\\if", \ref cmdifnot "\\ifnot", or \ref cmdelseif "\\elseif" 1481 command. 1482 1483 \sa sections \ref cmdif "\\if", \ref cmdifnot "\\ifnot", \ref cmdelseif "\\elseif", 1484 \ref cmdendif "\\endif." 1485 1486<hr> 1487\section cmdelseif \\elseif (section-label) 1488 1489 \addindex \\elseif 1490 Starts a conditional documentation section if the previous section 1491 was not enabled. A conditional section is 1492 disabled by default. To enable it you must put the 1493 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS" 1494 tag in the configuration file. The section label can be a logical expression 1495 build of section names, round brackets, && (AND), || (OR) and ! (NOT). 1496 Conditional blocks can be nested. A nested section is 1497 only enabled if all enclosing sections are enabled as well. 1498 1499 \sa sections \ref cmdif "\\if", \ref cmdifnot "\\ifnot", \ref cmdelse "\\else", 1500 \ref cmdendif "\\endif." 1501 1502<hr> 1503\section cmdendcond \\endcond 1504 1505 \addindex \\endcond 1506 Ends a conditional section that was started by \ref cmdcond "\\cond". 1507 1508 \sa section \ref cmdcond "\\cond". 1509 \note Due to the moment of parsing the \c \\endcond and \ref cmdcond "\\cond" commands cannot 1510 be used in \ref cfg_aliases "ALIASES". 1511 1512<hr> 1513\section cmdendif \\endif 1514 1515 \addindex \\endif 1516 Ends a conditional section that was started by \ref cmdif "\\if" or \ref cmdifnot "\\ifnot" 1517 For each \ref cmdif "\\if" or \ref cmdifnot "\\ifnot" one and only one matching 1518 \ref cmdendif "\\endif" must follow. 1519 1520 \sa sections \ref cmdif "\\if", \ref cmdifnot "\\ifnot", \ref cmdelse "\\else", 1521 \ref cmdelseif "\\elseif." 1522 1523<hr> 1524\section cmdexception \\exception <exception-object> { exception description } 1525 1526 \addindex \\exception 1527 Starts an exception description for an exception object with name 1528 \<exception-object\>. Followed by a description of the exception. 1529 The existence of the exception object is not checked. 1530 The text of the paragraph has no special internal structure. All visual 1531 enhancement commands may be used inside the paragraph. 1532 Multiple adjacent \c \\exception commands will be joined into a single paragraph. 1533 Each exception description will start on a new line. 1534 The \c \\exception description ends when a blank line or some other 1535 sectioning command is encountered. See section \ref cmdfn "\\fn" for an 1536 example. 1537 1538<hr> 1539\section cmdif \\if (section-label) 1540 1541 \addindex \\if 1542 Starts a conditional documentation section. The section ends 1543 with a matching \ref cmdendif "\\endif" command. A conditional section is 1544 disabled by default. To enable it you must put the 1545 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS" 1546 tag in the configuration file. 1547 1548 The section label can be a logical expression 1549 build of section names, round brackets, && (AND), || (OR) and ! (NOT). 1550 If you use an expression you need to wrap it in round brackets, i.e 1551 <tt>\\if (!LABEL1 && LABEL2)</tt>. 1552 1553 Conditional blocks can be nested. A nested section is 1554 only enabled if all enclosing sections are enabled as well. 1555 1556 The \c \\if and corresponding \ref cmdendif "\\endif" have to be in the same comment block. 1557 When a conditional block needs to span more than one comment block one has to use 1558 \ref cmdcond "\\cond" ... \ref cmdendcond "\\endcond". 1559 1560 \par Example: 1561\verbatim 1562 /*! Unconditionally shown documentation. 1563 * \if Cond1 1564 * Only included if Cond1 is set. 1565 * \endif 1566 * \if Cond2 1567 * Only included if Cond2 is set. 1568 * \if Cond3 1569 * Only included if Cond2 and Cond3 are set. 1570 * \endif 1571 * More text. 1572 * \endif 1573 * Unconditional text. 1574 */ 1575\endverbatim 1576 1577 You can also use conditional commands inside aliases. To 1578 document a class in two languages you could for instance use: 1579 1580\par Example 2: 1581\verbatim 1582/*! \english 1583 * This is English. 1584 * \endenglish 1585 * \dutch 1586 * Dit is Nederlands. 1587 * \enddutch 1588 */ 1589class Example 1590{ 1591}; 1592\endverbatim 1593 1594 Where the following aliases are defined in the configuration file: 1595 1596\verbatim 1597ALIASES = "english=\if english" \ 1598 "endenglish=\endif" \ 1599 "dutch=\if dutch" \ 1600 "enddutch=\endif" 1601\endverbatim 1602 1603 and \ref cfg_enabled_sections "ENABLED_SECTIONS" can be used to enable either \c english or \c dutch. 1604 1605 \sa sections \ref cmdendif "\\endif", \ref cmdifnot "\\ifnot", 1606 \ref cmdelse "\\else", \ref cmdelseif "\\elseif", 1607 \ref cmdcond "\\cond", \ref cmdendcond "\\endcond", and 1608 \ref cfg_enabled_sections "ENABLED_SECTIONS". 1609 1610<hr> 1611\section cmdifnot \\ifnot (section-label) 1612 1613 \addindex \\ifnot 1614 Starts a conditional documentation section. The section ends 1615 with a matching \ref cmdendif "\\endif" command. This conditional section is 1616 enabled by default. To disable it you must put the 1617 section-label after the \ref cfg_enabled_sections "ENABLED_SECTIONS" 1618 tag in the configuration file. The section label can be a logical expression 1619 build of section names, round brackets, && (AND), || (OR) and ! (NOT). 1620 1621 \sa sections \ref cmdendif "\\endif", \ref cmdif "\\if", 1622 \ref cmdelse "\\else", and \ref cmdelseif "\\elseif", 1623 \ref cmdcond "\\cond", \ref cmdendcond "\\endcond", and 1624 \ref cfg_enabled_sections "ENABLED_SECTIONS". 1625 1626<hr> 1627\section cmdinvariant \\invariant { description of invariant } 1628 1629 \addindex \\invariant 1630 Starts a paragraph where the invariant of an entity can be described. 1631 The paragraph will be indented. 1632 The text of the paragraph has no special internal structure. All visual 1633 enhancement commands may be used inside the paragraph. 1634 Multiple adjacent \c \\invariant commands will be joined into a single paragraph. 1635 Each invariant description will start on a new line. 1636 Alternatively, one \c \\invariant command may mention 1637 several invariants. The \c \\invariant command ends when a blank line or some other 1638 sectioning command is encountered. 1639 1640<hr> 1641\section cmdnote \\note { text } 1642 1643 \addindex \\note 1644 Starts a paragraph where a note can be entered. The paragraph will be 1645 indented. The text of the paragraph has no special internal structure. 1646 All visual enhancement commands may be used inside the paragraph. 1647 Multiple adjacent \c \\note commands will be joined into a single paragraph. 1648 Each note description will start on a new line. 1649 Alternatively, one \c \\note command may mention 1650 several notes. The \c \\note command ends when a blank line or some other 1651 sectioning command is encountered. See section \ref cmdpar "\\par" 1652 for an example. 1653 1654<hr> 1655\section cmdpar \\par [(paragraph title)] { paragraph } 1656 1657 \addindex \\par 1658 If a paragraph title is given this command starts a paragraph with a 1659 user defined heading. The heading extends until the end of the 1660 line. The paragraph following the command will be indented. 1661 1662 If no paragraph title is given this command will start a new paragraph. 1663 This will also work inside other paragraph commands 1664 (like \ref cmdparam "\\param" or \ref cmdwarning "\\warning") without ending that command. 1665 1666 The text of the paragraph has no special internal structure. All visual 1667 enhancement commands may be used inside the paragraph. 1668 The \c \\par command ends when a blank line or some other 1669 sectioning command is encountered. 1670 1671 \par Example: 1672 \include par.cpp 1673 \htmlonly 1674 Click <a href="examples/par/html/class_par___test.html">here</a> 1675 for the corresponding HTML documentation that is generated by doxygen. 1676 \endhtmlonly 1677 \latexonly 1678 See \hyperlink{class_par___test}{Par example} 1679 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 1680 \endlatexonly 1681 1682<hr> 1683\section cmdparam \\param '['dir']' <parameter-name> { parameter description } 1684 1685 \addindex \\param 1686 Starts a parameter description for a function parameter with name 1687 \<parameter-name\>, followed by a description of the parameter. 1688 The existence of the parameter is checked and a warning is given if 1689 the documentation of this (or any other) parameter is missing or not 1690 present in the function declaration or definition. 1691 1692 The \c \\param command has an optional attribute, `dir`, specifying the direction 1693 of the parameter. Possible values are "[in]", "[in,out]", and "[out]", 1694 note the [square] brackets in this description. 1695 When a parameter is both input and output, [in,out] is used as attribute. 1696 Here is an example for the function \c memcpy: 1697 \code 1698/*! 1699 * Copies bytes from a source memory area to a destination memory area, 1700 * where both areas may not overlap. 1701 * @param[out] dest The memory area to copy to. 1702 * @param[in] src The memory area to copy from. 1703 * @param[in] n The number of bytes to copy 1704 */ 1705void memcpy(void *dest, const void *src, size_t n); 1706 \endcode 1707 1708 The parameter description is a paragraph with no special internal structure. 1709 All visual enhancement commands may be used inside the paragraph. 1710 1711 Multiple adjacent \c \\param commands will be joined into a single paragraph. 1712 Each parameter description will start on a new line. 1713 The \c \\param description ends when a blank line or some other 1714 sectioning command is encountered. See section \ref cmdfn "\\fn" for an 1715 example. 1716 1717 Note that you can also document multiple parameters with a single 1718 \c \\param command using a comma separated list. Here is an example: 1719 1720\code 1721/** Sets the position. 1722 * @param x,y,z Coordinates of the position in 3D space. 1723 */ 1724void setPosition(double x,double y,double z,double t) 1725{ 1726} 1727\endcode 1728 1729 Note that for PHP one can also specify the type (or types if you 1730 separate them with a pipe symbol) which are allowed for a parameter 1731 (as this is not part of the definition). 1732 The syntax is the same as for the `phpDocumentor`, i.e. 1733\verbatim 1734@param datatype1|datatype2 $paramname description 1735\endverbatim 1736 1737<hr> 1738\section cmdparblock \\parblock 1739 \addindex \\parblock 1740 For commands that expect a single paragraph as argument 1741 (such as \ref cmdpar "\\par", \ref cmdparam "\\param" and \ref cmdwarning "\\warning"), 1742 the \ref cmdparblock "\\parblock" command allows to start a 1743 description that covers multiple paragraphs, which then ends with 1744 \ref cmdendparblock "\\endparblock". 1745 1746 Example: 1747\verbatim 1748/** Example of a param command with a description consisting of two paragraphs 1749 * \param p 1750 * \parblock 1751 * First paragraph of the param description. 1752 * 1753 * Second paragraph of the param description. 1754 * \endparblock 1755 * Rest of the comment block continues. 1756 */ 1757\endverbatim 1758 Note that the \c \\parblock command may also appear directly after 1759 \ref cmdparam "\\param"'s first argument. 1760 1761<hr> 1762\section cmdendparblock \\endparblock 1763 \addindex \\endparblock 1764 This ends a block of paragraphs started with \ref cmdparblock "\\parblock". 1765 1766<hr> 1767\section cmdtparam \\tparam <template-parameter-name> { description } 1768 1769 \addindex \\tparam 1770 Starts a template parameter for a class or function template parameter 1771 with name \<template-parameter-name\>, followed by a description of the 1772 template parameter. 1773 1774 Otherwise similar to \ref cmdparam "\\param". 1775 1776<hr> 1777\section cmdpost \\post { description of the postcondition } 1778 1779 \addindex \\post 1780 Starts a paragraph where the postcondition of an entity can be described. 1781 The paragraph will be indented. 1782 The text of the paragraph has no special internal structure. All visual 1783 enhancement commands may be used inside the paragraph. 1784 Multiple adjacent \c \\post commands will be joined into a single paragraph. 1785 Each postcondition will start on a new line. 1786 Alternatively, one \c \\post command may mention 1787 several postconditions. The \c \\post command ends when a blank line or some other 1788 sectioning command is encountered. 1789 1790<hr> 1791\section cmdpre \\pre { description of the precondition } 1792 1793 \addindex \\pre 1794 Starts a paragraph where the precondition of an entity can be described. 1795 The paragraph will be indented. 1796 The text of the paragraph has no special internal structure. All visual 1797 enhancement commands may be used inside the paragraph. 1798 Multiple adjacent \c \\pre commands will be joined into a single paragraph. 1799 Each precondition will start on a new line. 1800 Alternatively, one \c \\pre command may mention 1801 several preconditions. The \c \\pre command ends when a blank line or some other 1802 sectioning command is encountered. 1803 1804<hr> 1805\section cmdremark \\remark { remark text } 1806 1807 \addindex \\remark 1808 Starts a paragraph where one or more remarks may be entered. 1809 The paragraph will be indented. 1810 The text of the paragraph has no special internal structure. All visual 1811 enhancement commands may be used inside the paragraph. 1812 Multiple adjacent \c \\remark commands will be joined into a single paragraph. 1813 Each remark will start on a new line. 1814 Alternatively, one \c \\remark command may mention 1815 several remarks. The \c \\remark command ends when a blank line or some other 1816 sectioning command is encountered. 1817 1818<hr> 1819\section cmdremarks \\remarks { remark text } 1820 1821 \addindex \\remarks 1822 Equivalent to \ref cmdremark "\\remark". 1823 1824<hr> 1825\section cmdresult \\result { description of the result value } 1826 1827 \addindex \\result 1828 Equivalent to \ref cmdreturn "\\return". 1829 1830<hr> 1831\section cmdreturn \\return { description of the return value } 1832 1833 \addindex \\return 1834 Starts a return value description for a function. 1835 The text of the paragraph has no special internal structure. All visual 1836 enhancement commands may be used inside the paragraph. 1837 Multiple adjacent \c \\return commands will be joined into a single paragraph. 1838 The \c \\return description ends when a blank line or some other 1839 sectioning command is encountered. See section \ref cmdfn "\\fn" for an 1840 example. 1841 1842<hr> 1843\section cmdreturns \\returns { description of the return value } 1844 1845 \addindex \\returns 1846 Equivalent to \ref cmdreturn "\\return". 1847 1848<hr> 1849\section cmdretval \\retval <return value> { description } 1850 1851 \addindex \\retval 1852 Starts a description for a function's return value with name 1853 \<return value\>, followed by a description of the return value. 1854 The text of the paragraph that forms the description has no special 1855 internal structure. All visual enhancement commands may be used inside the 1856 paragraph. 1857 Multiple adjacent \c \\retval commands will be joined into a single paragraph. 1858 Each return value description will start on a new line. 1859 The \c \\retval description ends when a blank line or some other 1860 sectioning command is encountered. 1861 1862<hr> 1863\section cmdsa \\sa { references } 1864 1865 \addindex \\sa 1866 Starts a paragraph where one or more cross-references to classes, 1867 functions, methods, variables, files or URL may be specified. 1868 Two names joined by either <code>::</code> or <code>\#</code> 1869 are understood as referring to a class and one of its members. 1870 One of several overloaded methods or constructors 1871 may be selected by including a parenthesized list of argument types after 1872 the method name. 1873 1874 Synonymous to \ref cmdsee "\\see". 1875 1876 \sa section \ref autolink "autolink" for information on how to create links 1877 to objects. 1878 1879<hr> 1880\section cmdsee \\see { references } 1881 1882 \addindex \\see 1883 Equivalent to \ref cmdsa "\\sa". Introduced for compatibility with Javadoc. 1884 1885<hr> 1886\section cmdshort \\short { short description } 1887 1888 \addindex \\short 1889 Equivalent to \ref cmdbrief "\\brief". 1890 1891<hr> 1892\section cmdsince \\since { text } 1893 1894 \addindex \\since 1895 This command can be used to specify since when (version or time) an 1896 entity is available. The paragraph that follows \c \\since does not have any 1897 special internal structure. All visual enhancement commands may be 1898 used inside the paragraph. The \c \\since description ends when a blank 1899 line or some other sectioning command is encountered. 1900 1901<hr> 1902\section cmdtest \\test { paragraph describing a test case } 1903 1904 \addindex \\test 1905 Starts a paragraph where a test case can be described. 1906 The description will also add the test case to a separate test list. 1907 The two instances of the description will be cross-referenced. 1908 Each test case in the test list will be preceded by a header that 1909 indicates the origin of the test case. 1910 1911<hr> 1912\section cmdthrow \\throw <exception-object> { exception description } 1913 1914 \addindex \\throw 1915 Synonymous \ref cmdexception "\\exception". 1916 1917 \par Note: 1918 the command \ref cmdthrows "\\throws" is a synonym for this command. 1919 1920 \sa section \ref cmdexception "\\exception" 1921 1922<hr> 1923\section cmdthrows \\throws <exception-object> { exception description } 1924 1925 \addindex \\throws 1926 Equivalent to \ref cmdthrow "\\throw". 1927 1928<hr> 1929\section cmdtodo \\todo { paragraph describing what is to be done } 1930 1931 \addindex \\todo 1932 Starts a paragraph where a TODO item is described. 1933 The description will also add an item to a separate TODO list. 1934 The two instances of the description will be cross-referenced. 1935 Each item in the TODO list will be preceded by a header that 1936 indicates the origin of the item. 1937 1938<hr> 1939\section cmdversion \\version { version number } 1940 1941 \addindex \\version 1942 Starts a paragraph where one or more version strings may be entered. 1943 The paragraph will be indented. 1944 The text of the paragraph has no special internal structure. All visual 1945 enhancement commands may be used inside the paragraph. 1946 Multiple adjacent \c \\version commands will be joined into a single paragraph. 1947 Each version description will start on a new line. 1948 Alternatively, one \c \\version command may mention 1949 several version strings. 1950 The \\version command ends when a blank line or some other 1951 sectioning command is encountered. 1952 See section \ref cmdauthor "\\author" for an example. 1953 1954<hr> 1955\section cmdwarning \\warning { warning message } 1956 1957 \addindex \\warning 1958 Starts a paragraph where one or more warning messages may be entered. 1959 The paragraph will be indented. 1960 The text of the paragraph has no special internal structure. All visual 1961 enhancement commands may be used inside the paragraph. 1962 Multiple adjacent \c \\warning commands will be joined into a single paragraph. 1963 Each warning description will start on a new line. 1964 Alternatively, one \c \\warning command may mention 1965 several warnings. The \c \\warning command ends when a blank line or some other 1966 sectioning command is encountered. See section \ref cmdauthor "\\author" 1967 for an example. 1968 1969<hr> 1970\section cmdxrefitem \\xrefitem <key> "(heading)" "(list title)" { text } 1971 1972 \addindex \\xrefitem 1973 This command is a generalization of commands such as \ref cmdtodo "\\todo" 1974 and \ref cmdbug "\\bug". 1975 It can be used to create user-defined text sections which are automatically 1976 cross-referenced between the place of occurrence and a related page, 1977 which will be generated. On the related page all sections of 1978 the same type will be collected. 1979 1980 The first argument \<key\> is an 1981 identifier uniquely representing the type of the section. The second argument 1982 is a quoted string representing the heading of the section under which 1983 text passed as the fourth argument is put. The third argument (list title) 1984 is used as the title for the related page containing all items with the 1985 same key. The keys \c "todo", \c "test", \c "bug" and \c "deprecated" are predefined. 1986 1987 To get an idea on how to use the \c \\xrefitem command and what its effect 1988 is, consider the todo list, which (for English output) can be seen an 1989 alias for the command 1990 \verbatim \xrefitem todo "Todo" "Todo List" \endverbatim 1991 1992 Since it is very tedious and error-prone to repeat the first three 1993 parameters of the command for each section, the command is meant to 1994 be used in combination with the \ref cfg_aliases "ALIASES" option in the 1995 configuration file. 1996 To define a new command \c \\reminder, for instance, one should add the following 1997 line to the configuration file: 1998 \verbatim ALIASES += "reminder=\xrefitem reminders \"Reminder\" \"Reminders\"" \endverbatim 1999 Note the use of escaped quotes for the second and third argument of the 2000 \c \\xrefitem command. 2001 2002 In case parameter "(heading)" is the empty string no heading is generated. This can be useful 2003 when used in combination with the \ref cmdpage "\\page" command e.g. 2004\verbatim 2005/** @page my_errors My Errors 2006 * @brief Errors page 2007 * 2008 * Errors page contents. 2009 */ 2010 2011/** \error ERROR 101: in case a file can not be opened. 2012 Check about file system read/write access. */ 2013#define MY_ERR_CANNOT_OPEN_FILE 101 2014 2015/** \error ERROR 102: in case a file can not be closed. 2016 Check about file system read/write access. */ 2017#define MY_ERR_CANNOT_CLOSE_FILE 102 2018\endverbatim 2019 with \c \\error defined as 2020 \verbatim ALIASES += "error=\xrefitem my_errors \"\" \"\"" \endverbatim 2021 2022<hr> 2023 2024\htmlonly</p><center><p>\endhtmlonly 2025<h2> 2026\htmlonly --- \endhtmlonly 2027Commands to create links 2028\htmlonly --- \endhtmlonly 2029</h2> 2030\htmlonly</p></center><p>\endhtmlonly 2031 2032<hr> 2033\section cmdaddindex \\addindex (text) 2034 2035 \addindex \\addindex 2036 This command adds (text) to the \LaTeX , DocBook and RTF index. 2037 2038<hr> 2039\section cmdanchor \\anchor <word> 2040 2041 \addindex \\anchor 2042 This command places an invisible, named anchor into the documentation 2043 to which you can refer with the \ref cmdref "\\ref" command. 2044 2045 \sa section \ref cmdref "\\ref". 2046 2047<hr> 2048\section cmdcite \\cite <label> 2049 2050 \addindex \\cite 2051 Adds a bibliographic reference in the text and in the list of bibliographic 2052 references. The \<label\> must be a valid BibTeX label that can be found 2053 in one of the .bib files listed in \ref cfg_cite_bib_files "CITE_BIB_FILES". 2054 For the \LaTeX output the formatting of the reference in the text can be 2055 configured with \ref cfg_latex_bib_style "LATEX_BIB_STYLE". For other 2056 output formats a fixed representation is used. Note that using this 2057 command requires the \c bibtex tool to be present in the search path. 2058 2059<hr> 2060\section cmdendlink \\endlink 2061 2062 \addindex \\endlink 2063 This command ends a link that is started with the \ref cmdlink "\\link" command. 2064 2065 \sa section \ref cmdlink "\\link". 2066 2067<hr> 2068\section cmdlink \\link <link-object> 2069 2070 \addindex \\link 2071 The links that are automatically generated by doxygen always have the 2072 name of the object they point to as link-text. 2073 2074 The \c \\link command can be used to create a link to an object (a file, 2075 class, or member) with a user specified link-text. 2076 The link command should end with an \ref cmdendlink "\\endlink" command. All text between 2077 the \c \\link and \ref cmdendlink "\\endlink" commands serves as text for a link to 2078 the \<link-object\> specified as the first argument of \c \\link. 2079 2080 \sa Section \ref autolink "autolink" for more information on automatically 2081 generated links and valid link-objects. 2082 2083<hr> 2084\section cmdref \\ref <name> ["(text)"] 2085 2086 \addindex \\ref 2087 Creates a reference to a named section, subsection, page or anchor. 2088 For HTML documentation the reference command will generate a link to 2089 the section. For a section or subsection the title of the section will be 2090 used as the text of the link. For an anchor the optional text between quotes 2091 will be used or \<name\> if no text is specified. 2092 For \LaTeX documentation the reference command will 2093 generate a section number for sections or the text followed by a 2094 page number if \<name\> refers to an anchor. 2095 2096 \sa 2097 Section \ref cmdpage "\\page" for an example of the \c \\ref command. 2098 2099<hr> 2100\section cmdrefitem \\refitem <name> 2101 \addindex \\refitem 2102 Just like the \ref cmdref "\\ref" command, this command creates a reference 2103 to a named section, but this reference appears in a list that is started by 2104 \ref cmdsecreflist "\\secreflist" 2105 and ends with \ref cmdendsecreflist "\\endsecreflist". 2106 An example of such a list can be seen 2107 \ref showsecreflist "at the top of the page". 2108 2109<hr> 2110\section cmdsecreflist \\secreflist 2111 \addindex \\secreflist 2112 Starts an index list of item, created with \ref cmdrefitem "\\refitem" 2113 that each link to a named section. 2114 2115<hr> 2116\section cmdendsecreflist \\endsecreflist 2117 \addindex \\endsecreflist 2118 End an index list started with \ref cmdsecreflist "\\secreflist". 2119 2120<hr> 2121\section cmdsubpage \\subpage <name> ["(text)"] 2122 2123 \addindex \\subpage 2124 This command can be used to create a hierarchy of pages. The 2125 same structure can be made using the \ref cmddefgroup "\\defgroup" and 2126 \ref cmdingroup "\\ingroup" commands, but for pages the \c \\subpage command 2127 is often more convenient. The main page (see \ref cmdmainpage "\\mainpage") 2128 is typically the root of hierarchy. 2129 2130 This command behaves similar as \ref cmdref "\\ref" in the sense that 2131 it creates a reference to a page labeled \<name\> with the optional 2132 link text as specified in the second argument. 2133 2134 It differs from the \ref cmdref "\\ref" command in that it only works for pages, 2135 and creates a parent-child relation between pages, where the 2136 child page (or sub page) is identified by label \<name\>. 2137 2138 See the \ref cmdsection "\\section" 2139 and \ref cmdsubsection "\\subsection" commands if you want to add structure 2140 without creating multiple pages. 2141 2142 \note Each page can be the sub page of only one other page and 2143 no cyclic relations are allowed, i.e. the page hierarchy must have a tree 2144 structure. 2145 2146 Here is an example: 2147\verbatim 2148/*! \mainpage A simple manual 2149 2150Some general info. 2151 2152This manual is divided in the following sections: 2153- \subpage intro 2154- \subpage advanced "Advanced usage" 2155*/ 2156 2157//----------------------------------------------------------- 2158 2159/*! \page intro Introduction 2160This page introduces the user to the topic. 2161Now you can proceed to the \ref advanced "advanced section". 2162*/ 2163 2164//----------------------------------------------------------- 2165 2166/*! \page advanced Advanced Usage 2167This page is for advanced users. 2168Make sure you have first read \ref intro "the introduction". 2169*/ 2170\endverbatim 2171 2172<hr> 2173\section cmdtableofcontents \\tableofcontents['{'[option[:level]][,option[:level]]*'}'] 2174 2175 \addindex \\tableofcontents 2176 Creates a table of contents at the top of a page, listing all 2177 sections and subsections in the page. The `option` can be `HTML` or `LaTeX` 2178 or `XML` or `DocBook`. When a `level` is specified this means the maximum nesting level 2179 that is shown. The value of `level` should be in the range 1..5, values outside 2180 this range are considered to be 5. In case no `level` is specified `level` is 2181 set to 5 (show all) 2182 In case no `option`. is specified \c \\tableofcontents acts as if just the 2183 `option` `HTML` and `XML` was specified. In case of multiple \c \\tableofcontents 2184 commands in a page the `option`(s) will be used additional to the already 2185 specified `option`(s), but only the last `level` of an `option` is valid. 2186 2187 \warning This command only works inside related page documentation and 2188 \e not in other documentation blocks and only has effect in the 2189 specified output! 2190 2191<hr> 2192\section cmdsection \\section <section-name> (section title) 2193 2194 \addindex \\section 2195 Creates a section with name \<section-name\>. The title of the 2196 section should be specified as the second argument of the \c \\section 2197 command. 2198 2199 \warning This command only works inside related page documentation and 2200 \e not in other documentation blocks! 2201 2202 \sa 2203 Section \ref cmdpage "\\page" for an example of the 2204 \c \\section command. 2205 2206<hr> 2207\section cmdsubsection \\subsection <subsection-name> (subsection title) 2208 2209 \addindex \\subsection 2210 Creates a subsection with name \<subsection-name\>. The title of the 2211 subsection should be specified as the second argument of the \c \\subsection 2212 command. 2213 2214 \warning This command only works inside a section of a related page 2215 documentation block and 2216 \e not in other documentation blocks! 2217 2218 \sa 2219 Section \ref cmdpage "\\page" for an example of the 2220 \c \\subsection command. 2221 2222<hr> 2223\section cmdsubsubsection \\subsubsection <subsubsection-name> (subsubsection title) 2224 2225 \addindex \\subsubsection 2226 Creates a subsubsection with name \<subsubsection-name\>. The title of the 2227 subsubsection should be specified as the second argument of the 2228 \c \\subsubsection command. 2229 2230 \warning This command only works inside a subsection of a 2231 related page documentation block and 2232 \e not in other documentation blocks! 2233 2234 \sa 2235 Section \ref cmdpage "\\page" for an example of the 2236 \ref cmdsection "\\section" command and 2237 \ref cmdsubsection "\\subsection" command. 2238 2239<hr> 2240\section cmdparagraph \\paragraph <paragraph-name> (paragraph title) 2241 2242 \addindex \\paragraph 2243 Creates a named paragraph with name \<paragraph-name\>. The title of the 2244 paragraph should be specified as the second argument of the 2245 \c \\paragraph command. 2246 2247 \warning This command only works inside a subsubsection of a 2248 related page documentation block and 2249 \e not in other documentation blocks! 2250 2251<hr> 2252 2253\htmlonly</p><center><p>\endhtmlonly 2254<h2> 2255\htmlonly --- \endhtmlonly 2256Commands for displaying examples 2257\htmlonly --- \endhtmlonly 2258</h2> 2259\htmlonly</p></center><p>\endhtmlonly 2260 2261<hr> 2262\section cmddontinclude \\dontinclude['{lineno}'] <file-name> 2263 2264 \addindex \\dontinclude 2265 This command can be used to parse a source file without actually 2266 verbatim including it in the documentation (as the \ref cmdinclude "\\include" command does). 2267 This is useful if you want to divide the source file into smaller pieces and 2268 add documentation between the pieces. 2269 Source files or directories can be specified using the 2270 \ref cfg_example_path "EXAMPLE_PATH" 2271 tag of doxygen's configuration file. 2272 2273 You can add option `{lineno}` to enable line numbers for the included code if desired. 2274 2275 The class and member declarations and definitions inside the code fragment 2276 are 'remembered' during the parsing of the comment block that contained 2277 the \c \\dontinclude command. 2278 2279 For line by line descriptions of source files, one or more lines 2280 of the example can be displayed using the \ref cmdline "\\line", 2281 \ref cmdskip "\\skip", \ref cmdskipline "\\skipline", and 2282 \ref cmduntil "\\until" commands. An internal pointer is used for these commands. The 2283 \c \\dontinclude command sets the pointer to the first line of the example. 2284 2285 \par Example: 2286 \include include.cpp 2287 Where the example file \c include_test.cpp looks as follows: 2288 \include include_test.cpp 2289 \htmlonly 2290 Click <a href="examples/include/html/pag_example.html">here</a> 2291 for the corresponding HTML documentation that is generated by doxygen. 2292 \endhtmlonly 2293 \latexonly 2294 See \hyperlink{include_example}{Include example} 2295 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen. 2296 \endlatexonly 2297 2298 \sa sections \ref cmdline "\\line", \ref cmdskip "\\skip", 2299 \ref cmdskipline "\\skipline", \ref cmduntil "\\until", and 2300 \ref cmdinclude "\\include". 2301 2302<hr> 2303\section cmdinclude \\include['{'option'}'] <file-name> 2304 2305 \addindex \\include 2306 This command can be used to include a source file as a block of code. 2307 The command takes the name of an include file as an argument. 2308 Source files or directories can be specified using the 2309 \ref cfg_example_path "EXAMPLE_PATH" 2310 tag of doxygen's configuration file. 2311 2312 If \<file-name\> itself is not unique for the set of example files specified 2313 by the \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part 2314 of the absolute path to disambiguate it. 2315 2316 Using the \c \\include command is equivalent to inserting the file into 2317 the documentation block and surrounding it 2318 with \ref cmdcode "\\code" and \ref cmdendcode "\\endcode" commands. 2319 2320 The main purpose of the \c \\include command is to avoid code 2321 duplication in case of example blocks that consist of multiple 2322 source and header files. 2323 2324 For a line by line description of a source files use the 2325 \ref cmddontinclude "\\dontinclude" command in combination with 2326 the \ref cmdline "\\line", \ref cmdskip "\\skip", 2327 \ref cmdskipline "\\skipline", 2328 and \ref cmduntil "\\until" commands. 2329 2330 Alternatively, the \ref cmdsnippet "\\snippet" command can be used to 2331 include only a fragment of a source file. For this to work the 2332 fragment has to be marked. 2333 2334 \note Doxygen's special commands do not work inside blocks of code. 2335 It is allowed to nest C-style comments inside a code block though. 2336 2337 The `option` can either be `lineno` or `doc`. 2338 The `option` `lineno` can be used to enable line numbers for the included code if desired. 2339 The `option` `doc` can be used to treat the file as documentation rather than code. 2340 2341 \note When using the `{doc}` option, 2342 some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with 2343 this command due to the moment of parsing. 2344 2345 \note The included documentation should not have comment signs in it as they will appear 2346 in the documentation as well. 2347 2348 \sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude", 2349 \ref cmdverbatim "\\verbatim", \ref cmdincludedoc "\\includedoc", and 2350 \ref cmdsnippet "\\snippet". 2351 2352<hr> 2353\section cmdincludelineno \\includelineno <file-name> 2354 2355 \addindex \\includelineno 2356 This command is obsolete and is still supported for backward compatibility reasons, 2357 it works the same way as \ref cmdinclude "\\include{lineno}" 2358 2359 \sa sections \ref cmdinclude "\\include{lineno}". 2360 2361<hr> 2362\section cmdincludedoc \\includedoc <file-name> 2363 2364 \addindex \\includedoc 2365 This command is obsolete and is still supported for backward compatibility reasons, 2366 it works the same way as \ref cmdinclude "\\include{doc}" 2367 2368 \sa section \ref cmdinclude "\\include{doc}". 2369 2370<hr> 2371\section cmdline \\line ( pattern ) 2372 2373 \addindex \\line 2374 This command searches line by line through the example that was last 2375 included using \ref cmdinclude "\\include" or 2376 \ref cmddontinclude "\\dontinclude" until it finds a non-blank 2377 line. If that line contains the specified pattern, it is written 2378 to the output. 2379 2380 The internal pointer that is used to keep track of the current line in 2381 the example, is set to the start of the line following the non-blank 2382 line that was found (or to the end of the example if no such line could 2383 be found). 2384 2385 See section \ref cmddontinclude "\\dontinclude" for an example. 2386 2387<hr> 2388\section cmdskip \\skip ( pattern ) 2389 2390 \addindex \\skip 2391 This command searches line by line through the example that was last 2392 included using \ref cmdinclude "\\include" or 2393 \ref cmddontinclude "\\dontinclude" until it finds a line that contains 2394 the specified pattern. 2395 2396 The internal pointer that is used to keep track of the current line in 2397 the example, is set to the start of the line that contains the specified 2398 pattern (or to the end of the example if the pattern could not be found). 2399 2400 See section \ref cmddontinclude "\\dontinclude" for an example. 2401 2402<hr> 2403\section cmdskipline \\skipline ( pattern ) 2404 2405 \addindex \\skipline 2406 This command searches line by line through the example that was last 2407 included using \ref cmdinclude "\\include" or 2408 \ref cmddontinclude "\\dontinclude" until it finds a line that contains 2409 the specified pattern. It then writes the line to the output. 2410 2411 The internal pointer that is used to keep track of the current line in 2412 the example, is set to the start of the line following the line that is 2413 written (or to the end of the example if the pattern could not be found). 2414 2415 \par Note: 2416 The command: 2417 \verbatim\skipline pattern\endverbatim 2418 is equivalent to: 2419\verbatim 2420\skip pattern 2421\line pattern\endverbatim 2422 2423 See section \ref cmddontinclude "\\dontinclude" for an example. 2424 2425<hr> 2426\section cmdsnippet \\snippet['{'option'}'] <file-name> ( block_id ) 2427 2428 \addindex \\snippet 2429 Where the \ref cmdinclude "\\include" command can be used to include 2430 a complete file as source code, this command can be used to quote only 2431 a fragment of a source file. In case `this` is used as <file-name> the 2432 current file is taken as file to take the snippet from. 2433 2434 For example, the putting the following command in the documentation, 2435 references a snippet in file \c example.cpp residing in a subdirectory 2436 which should be pointed to by \ref cfg_example_path "EXAMPLE_PATH". 2437 2438\verbatim 2439 \snippet snippets/example.cpp Adding a resource 2440\endverbatim 2441 2442 The text following the file name is the unique identifier for the snippet. 2443 This is used to delimit the quoted code in the relevant snippet file as 2444 shown in the following example that corresponds to the above \c \\snippet 2445 command: 2446 2447\code 2448 QImage image(64, 64, QImage::Format_RGB32); 2449 image.fill(qRgb(255, 160, 128)); 2450 2451//! [Adding a resource] 2452 document->addResource(QTextDocument::ImageResource, 2453 QUrl("mydata://image.png"), QVariant(image)); 2454//! [Adding a resource] 2455 ... 2456\endcode 2457 2458 Note that the lines containing the block markers will not be included, 2459 so the output will be: 2460 2461\code 2462 document->addResource(QTextDocument::ImageResource, 2463 QUrl("mydata://image.png"), QVariant(image)); 2464\endcode 2465 2466 Note also that the [block_id] markers should appear exactly twice in the 2467 source file. 2468 2469 The `option` can either be `lineno` or `doc`. 2470 The `option` `lineno` can be used to enable line numbers for the included code if desired. 2471 The `option` `doc` can be used to treat the file as documentation rather than code. 2472 2473 \note When using the `{doc}` option, 2474 some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with 2475 this command due to the moment of parsing. 2476 2477 \note The included documentation should not have comment signs in it as they will appear 2478 in the documentation as well. 2479 2480 see section \ref cmddontinclude "\\dontinclude" for an alternative way 2481 to include fragments of a source file that does not require markers. 2482 2483<hr> 2484\section cmdsnippetlineno \\snippetlineno <file-name> ( block_id ) 2485 2486 \addindex \\snippetlineno 2487 This command is obsolete and is still supported for backward compatibility reasons, 2488 it works the same way as \ref cmdsnippet "\\snippet{lineno}" 2489 2490 \sa sections \ref cmdsnippet "\\snippet{lineno}" 2491 2492<hr> 2493\section cmdsnippetdoc \\snippetdoc <file-name> ( block_id ) 2494 2495 \addindex \\snippetdoc 2496 This command is obsolete and is still supported for backward compatibility reasons, 2497 it works the same way as \ref cmdsnippet "\\snippet{doc}" 2498 2499 \sa section \ref cmdsnippet "\\snippet{doc}" and \ref cmdinclude "\\include{doc}". 2500 2501<hr> 2502\section cmduntil \\until ( pattern ) 2503 2504 \addindex \\until 2505 This command writes all lines of the example that was last 2506 included using \ref cmdinclude "\\include" or 2507 \ref cmddontinclude "\\dontinclude" to the output, until it finds 2508 a line containing the specified pattern. The line containing the pattern 2509 will be written as well. 2510 2511 The internal pointer that is used to keep track of the current line in 2512 the example, is set to the start of the line following last written 2513 line (or to the end of the example if the pattern could not be found). 2514 2515 See section \ref cmddontinclude "\\dontinclude" for an example. 2516 2517<hr> 2518\section cmdverbinclude \\verbinclude <file-name> 2519 2520 \addindex \\verbinclude 2521 This command includes the contents of the file \<file-name\> verbatim in the documentation. 2522 The command is equivalent to pasting the contents of the file in the documentation and 2523 placing \ref cmdverbatim "\\verbatim" and \ref cmdendverbatim "\\endverbatim" 2524 commands around it. 2525 2526 Files or directories that doxygen should look for can be specified using the 2527 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2528 2529<hr> 2530\section cmdhtmlinclude \\htmlinclude ["[block]"] <file-name> 2531 2532 \addindex \\htmlinclude 2533 This command includes the contents of the file \<file-name\> as is in the HTML documentation 2534 and tagged with `<htmlonly>` in the generated XML output. 2535 The command is equivalent to pasting the contents of the file in the documentation and 2536 placing \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly" 2537 commands around it. 2538 2539 Normally the contents of the file indicated by \ref cmdhtmlinclude "\\htmlinclude" 2540 is inserted as-is. When you 2541 want to insert a HTML fragment that has block scope like a table or list 2542 which should appear outside \<p\>..\</p\>, this can lead to invalid HTML. 2543 You can use \\htmlinclude[block] to make doxygen 2544 end the current paragraph and restart after the file is included. 2545 2546 Files or directories that doxygen should look for can be specified using the 2547 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2548 2549 \sa section \ref cmdhtmlonly "\\htmlonly", 2550 \ref cmdlatexinclude "\\latexinclude", 2551 \ref cmdrtfinclude "\\rtfinclude", 2552 \ref cmdmaninclude "\\maninclude", 2553 \ref cmddocbookinclude "\\docbookinclude" and 2554 \ref cmdxmlinclude "\\xmlinclude". 2555 2556<hr> 2557 2558\section cmdlatexinclude \\latexinclude <file-name> 2559 2560 \addindex \\latexinclude 2561 This command includes the contents of the file \<file-name\> as is in the \LaTeX documentation 2562 and tagged with `<latexonly>` in the generated XML output. 2563 The command is equivalent to pasting the contents of the file in the documentation and 2564 placing \ref cmdlatexonly "\\latexonly" and \ref cmdendlatexonly "\\endlatexonly" 2565 commands around it. 2566 2567 Files or directories that doxygen should look for can be specified using the 2568 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2569 2570 \sa section \ref cmdlatexonly "\\latexonly", 2571 \ref cmdhtmlinclude "\\htmlinclude", 2572 \ref cmdrtfinclude "\\rtfinclude", 2573 \ref cmdmaninclude "\\maninclude", 2574 \ref cmddocbookinclude "\\docbookinclude" and 2575 \ref cmdxmlinclude "\\xmlinclude". 2576 2577<hr> 2578 2579\section cmdrtfinclude \\rtfinclude <file-name> 2580 2581 \addindex \\rtfinclude 2582 This command includes the contents of the file \<file-name\> as is in the RTF documentation 2583 and tagged with `<rtfonly>` in the generated XML output. 2584 The command is equivalent to pasting the contents of the file in the documentation and 2585 placing \ref cmdrtfonly "\\rtfonly" and \ref cmdendrtfonly "\\endrtfonly" 2586 commands around it. 2587 2588 Files or directories that doxygen should look for can be specified using the 2589 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2590 2591 \sa section \ref cmdrtfonly "\\rtfonly", 2592 \ref cmdhtmlinclude "\\htmlinclude", 2593 \ref cmdlatexinclude "\\latexinclude", 2594 \ref cmdmaninclude "\\maninclude", 2595 \ref cmddocbookinclude "\\docbookinclude" and 2596 \ref cmdxmlinclude "\\xmlinclude". 2597 2598<hr> 2599 2600\section cmdmaninclude \\maninclude <file-name> 2601 2602 \addindex \\maninclude 2603 This command includes the contents of the file \<file-name\> as is in the MAN documentation 2604 and tagged with `<manonly>` in the generated XML output. 2605 The command is equivalent to pasting the contents of the file in the documentation and 2606 placing \ref cmdmanonly "\\manonly" and \ref cmdendmanonly "\\endmanonly" 2607 commands around it. 2608 2609 Files or directories that doxygen should look for can be specified using the 2610 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2611 2612 \sa section \ref cmdmanonly "\\manonly", 2613 \ref cmdhtmlinclude "\\htmlinclude", 2614 \ref cmdlatexinclude "\\latexinclude", 2615 \ref cmdrtfinclude "\\rtfinclude", 2616 \ref cmddocbookinclude "\\docbookinclude" and 2617 \ref cmdxmlinclude "\\xmlinclude". 2618 2619<hr> 2620 2621\section cmddocbookinclude \\docbookinclude <file-name> 2622 2623 \addindex \\docbookinclude 2624 This command includes the contents of the file \<file-name\> as is in the DocBook documentation 2625 and tagged with `<docbookonly>` in the generated XML output. 2626 The command is equivalent to pasting the contents of the file in the documentation and 2627 placing \ref cmddocbookonly "\\docbookonly" and \ref cmdenddocbookonly "\\enddocbookonly" 2628 commands around it. 2629 2630 Files or directories that doxygen should look for can be specified using the 2631 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2632 2633 \sa section \ref cmddocbookonly "\\docbookonly", 2634 \ref cmdhtmlinclude "\\htmlinclude", 2635 \ref cmdlatexinclude "\\latexinclude", 2636 \ref cmdrtfinclude "\\rtfinclude", 2637 \ref cmdmaninclude "\\maninclude" and 2638 \ref cmdxmlinclude "\\xmlinclude". 2639 2640<hr> 2641 2642\section cmdxmlinclude \\xmlinclude <file-name> 2643 2644 \addindex \\xmlinclude 2645 This command includes contents of the file \<file-name\> as is in the XML documentation. 2646 The command is equivalent to pasting the contents of the file in the documentation and 2647 placing \ref cmdxmlonly "\\xmlonly" and \ref cmdendxmlonly "\\endxmlonly" 2648 commands around it. 2649 2650 Files or directories that doxygen should look for can be specified using the 2651 \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file. 2652 2653 \sa section \ref cmdxmlonly "\\xmlonly", 2654 \ref cmdhtmlinclude "\\htmlinclude", 2655 \ref cmdlatexinclude "\\latexinclude", 2656 \ref cmdrtfinclude "\\rtfinclude", 2657 \ref cmdmaninclude "\\maninclude" and 2658 \ref cmddocbookinclude "\\docbookinclude". 2659 2660<hr> 2661 2662\htmlonly</p><center><p>\endhtmlonly 2663<h2> 2664\htmlonly --- \endhtmlonly 2665Commands for visual enhancements 2666\htmlonly --- \endhtmlonly 2667</h2> 2668\htmlonly</p></center><p>\endhtmlonly 2669 2670\section cmda \\a <word> 2671 2672 \addindex \\a 2673 Displays the argument \<word\> in italics. 2674 Use this command to emphasize words. 2675 Use this command to refer to member arguments in the running text. 2676 2677 \par Example: 2678 \verbatim 2679 ... the \a x and \a y coordinates are used to ... 2680 \endverbatim 2681 This will result in the following text:<br><br> 2682 ... the \a x and \a y coordinates are used to ... 2683 2684 Equivalent to \ref cmde "\\e" and \ref cmdem "\\em". 2685 To emphasize multiple words use \ref htmltag_EM "\<em\>"multiple words\ref htmltag_endEM "\</em\>". 2686 2687<hr> 2688\section cmdarg \\arg { item-description } 2689 2690 \addindex \\arg 2691 This command has one argument that continues until the first 2692 blank line or until another \c \\arg is encountered. 2693 The command can be used to generate a simple, not nested list of 2694 arguments. 2695 Each argument should start with a \c \\arg command. 2696 2697 \par Example: 2698 Typing: 2699 \verbatim 2700 \arg \c AlignLeft left alignment. 2701 \arg \c AlignCenter center alignment. 2702 \arg \c AlignRight right alignment 2703 2704 No other types of alignment are supported. 2705 \endverbatim 2706 will result in the following text:<br><br> 2707 <ul> 2708 <li> \c AlignLeft left alignment. 2709 <li> \c AlignCenter center alignment. 2710 <li> \c AlignRight right alignment 2711 </ul><br> 2712 No other types of alignment are supported. 2713 2714 \par Note: 2715 For nested lists, HTML commands should be used. 2716 2717 Equivalent to \ref cmdli "\\li" 2718 2719 2720<hr> 2721\section cmdb \\b <word> 2722 2723 \addindex \\b 2724 Displays the argument \<word\> using a bold font. 2725 Equivalent to \ref htmltag_B "\<b\>"word\ref htmltag_endB "\</b\>". 2726 To put multiple words in bold use \ref htmltag_B "\<b\>"multiple words\ref htmltag_endB "\</b\>". 2727 2728<hr> 2729\section cmdc \\c <word> 2730 2731 \addindex \\c 2732 Displays the argument \<word\> using a typewriter font. 2733 Use this to refer to a word of code. 2734 Equivalent to \ref htmltag_TT "\<tt\>"word\ref htmltag_endTT "\</tt\>". 2735 2736 \par Example: 2737 Typing: 2738 \verbatim 2739 ... This function returns \c void and not \c int ... 2740 \endverbatim 2741 will result in the following text:<br><br> 2742 ... This function returns \c void and not \c int ... 2743 2744 Equivalent to \ref cmdp "\\p" 2745 To have multiple words in typewriter font use \ref htmltag_TT "\<tt\>"multiple words\ref htmltag_endTT "\</tt\>". 2746 2747<hr> 2748\section cmdcode \\code['{'<word>'}'] 2749 2750 \addindex \\code 2751 Starts a block of code. A code block is treated differently 2752 from ordinary text. It is interpreted as source code. The names of 2753 classes and members and other documented entities are automatically 2754 replaced by links to the documentation. 2755 2756 By default the language that is assumed for syntax highlighting is based 2757 on the location where the \c \\code block was found. If this part of 2758 a Python file for instance, the syntax highlight will be done according 2759 to the Python syntax. 2760 2761 If it is unclear from the context which language is meant (for instance the 2762 comment is in a <code>.txt</code> or <code>.markdown</code> file) then you can also explicitly 2763 indicate the language, by putting the file extension typically 2764 that doxygen associated with the language in curly brackets after the 2765 code block. Here is an example: 2766 2767\verbatim 2768 \code{.py} 2769 class Python: 2770 pass 2771 \endcode 2772 2773 \code{.cpp} 2774 class Cpp {}; 2775 \endcode 2776\endverbatim 2777 2778 If the contents of the code block are in a language that doxygen cannot parse, doxygen 2779 will just show the output as-is. You can make this explicit using .unparsed, or by 2780 giving some other extension that doxygen doesn't support, e.g. 2781 2782\verbatim 2783 \code{.unparsed} 2784 Show this as-is please 2785 \endcode 2786 2787 \code{.sh} 2788 echo "This is a shell script" 2789 \endcode 2790\endverbatim 2791 2792 \sa section \ref cmdendcode "\\endcode" and section \ref cmdverbatim "\\verbatim". 2793 2794<hr> 2795\section cmdcopydoc \\copydoc <link-object> 2796 2797 \addindex \\copydoc 2798 Copies a documentation block from the object specified by \<link-object\> 2799 and pastes it at the location of the command. This command can be useful 2800 to avoid cases where a documentation block would otherwise have to be 2801 duplicated or it can be used to extend the documentation of an inherited 2802 member. 2803 2804 The link object can point to a member (of a class, file or group), 2805 a class, a namespace, a group, a page, or a file (checked in that order). 2806 Note that if the object pointed to is a member (function, variable, 2807 typedef, etc), the compound (class, file, or group) containing it 2808 should also be documented for the copying to work. 2809 2810 To copy the documentation for a member of a 2811 class one can, for instance, put the following in the documentation: 2812 2813\verbatim 2814 /*! @copydoc MyClass::myfunction() 2815 * More documentation. 2816 */ 2817\endverbatim 2818 2819 if the member is overloaded, you should specify the argument types 2820 explicitly (without spaces!), like in the following: 2821 2822\verbatim 2823 //! @copydoc MyClass::myfunction(type1,type2) 2824\endverbatim 2825 2826 Qualified names are only needed if the context in which the documentation 2827 block is found requires them. 2828 2829 The \c \\copydoc command can be used recursively, but cycles in the \c \\copydoc 2830 relation will be broken and flagged as an error. 2831 2832 Note that <code>\\copydoc foo()</code> is roughly equivalent to doing: 2833\verbatim 2834 \brief \copybrief foo() 2835 \details \copydetails foo() 2836\endverbatim 2837 See \ref cmdcopybrief "\\copybrief" and 2838 \ref cmdcopydetails "\\copydetails" for copying only the brief or 2839 detailed part of the comment block. 2840 2841<hr> 2842\section cmdcopybrief \\copybrief <link-object> 2843 2844 \addindex \\copybrief 2845Works in a similar way as \ref cmdcopydoc "\\copydoc" but will 2846only copy the brief description, not the detailed documentation. 2847 2848<hr> 2849\section cmdcopydetails \\copydetails <link-object> 2850 2851 \addindex \\copydetails 2852Works in a similar way as \ref cmdcopydoc "\\copydoc" but will 2853only copy the detailed documentation, not the brief description. 2854 2855<hr> 2856\section cmddocbookonly \\docbookonly 2857 2858 \addindex \\docbookonly 2859 Starts a block of text that only will be verbatim included in the 2860 generated DocBook documentation and tagged with `<docbookonly>` in the generated 2861 XML output. The block ends with a 2862 \ref cmdenddocbookonly "\\enddocbookonly" command. 2863 2864 \sa section \ref cmdmanonly "\\manonly", 2865 \ref cmdlatexonly "\\latexonly", 2866 \ref cmdrtfonly "\\rtfonly", 2867 \ref cmdxmlonly "\\xmlonly", 2868 \ref cmdhtmlonly "\\htmlonly" and 2869 \ref cmddocbookinclude "\\docbookinclude". 2870 2871<hr> 2872\section cmddot \\dot ["caption"] [<sizeindication>=<size>] 2873 2874 \addindex \\dot 2875 Starts a text fragment which should contain a valid description of a 2876 dot graph. The text fragment ends with \ref cmdenddot "\\enddot". 2877 Doxygen will pass the text on to dot and include the resulting 2878 image (and image map) into the output. 2879 2880 The first argument is optional and can be used to specify the caption 2881 that is displayed below the image. This argument has to be specified 2882 between quotes even if it does not contain any spaces. The quotes are 2883 stripped before the caption is displayed. 2884 2885 The second argument is also optional and can be used to specify the 2886 width or height of the image. 2887 For a description of the possibilities see the paragraph 2888 \ref image_sizeindicator "Size indication" with the 2889 \ref cmdimage "\\image" command. 2890 2891 The nodes of a graph can be made clickable by using the URL attribute. 2892 By using the command \ref cmdref "\\ref" inside the URL value you can conveniently 2893 link to an item inside doxygen. Here is an example: 2894 2895 \note usage of this command requires that \ref cfg_have_dot "HAVE_DOT" is set to \c YES 2896 2897 \note doxygen creates a temporary file that is automatically removed unless 2898 the \ref cfg_dot_cleanup "DOT_CLEANUP" tag is set to `NO`. 2899 2900\code 2901/*! class B */ 2902class B {}; 2903 2904/*! class C */ 2905class C {}; 2906 2907/*! \mainpage 2908 * 2909 * Class relations expressed via an inline dot graph: 2910 * \dot 2911 * digraph example { 2912 * node [shape=record, fontname=Helvetica, fontsize=10]; 2913 * b [ label="class B" URL="\ref B"]; 2914 * c [ label="class C" URL="\ref C"]; 2915 * b -> c [ arrowhead="open", style="dashed" ]; 2916 * } 2917 * \enddot 2918 * Note that the classes in the above graph are clickable 2919 * (in the HTML output). 2920 */ 2921\endcode 2922 2923<hr> 2924\section cmdemoji \\emoji "name" 2925 2926This command will produce an emoji character given its name. 2927 2928The supported names are the ones also supported by GitHub and listed here 2929https://gist.github.com/rxaviers/7360908 2930 2931You can use the name with or without colons, i.e. 2932`\emoji smile` is the same as writing `\emoji :smile:`. 2933When an emoji is not supported the name with by places in the 2934text with in between colons, i.e. `\emoji unsupported` will produce 2935`:unsupported:` in the output. Doxygen will also give a warning message. 2936 2937See also the \ref emojisup "emoji support page" for details. 2938 2939<hr> 2940\section cmdmsc \\msc ["caption"] [<sizeindication>=<size>] 2941 2942 \addindex \\msc 2943 Starts a text fragment which should contain a valid description of a 2944 message sequence chart. See http://www.mcternan.me.uk/mscgen/ for examples. 2945 The text fragment ends with \ref cmdendmsc "\\endmsc". 2946 2947 The first argument is optional and can be used to specify the caption 2948 that is displayed below the image. This argument has to be specified 2949 between quotes even if it does not contain any spaces. The quotes are 2950 stripped before the caption is displayed. 2951 2952 The second argument is also optional and can be used to specify the 2953 width or height of the image. 2954 For a description of the possibilities see the paragraph 2955 \ref image_sizeindicator "Size indication" with the 2956 \ref cmdimage "\\image" command. 2957 2958 \note The text fragment should only include the part of the message 2959 sequence chart that is 2960 within the <code>msc {...}</code> block (this is different from 2961 \ref cmdmscfile "\\mscfile"). 2962 \note mscgen is now built in into doxygen 2963 \note doxygen creates a temporary file that is automatically removed unless 2964 the \ref cfg_dot_cleanup "DOT_CLEANUP" tag is set to `NO`. 2965 2966Here is an example of the use of the \c \\msc command. 2967\code 2968/** Sender class. Can be used to send a command to the server. 2969 * The receiver will acknowledge the command by calling Ack(). 2970 * \msc 2971 * Sender,Receiver; 2972 * Sender->Receiver [label="Command()", URL="\ref Receiver::Command()"]; 2973 * Sender<-Receiver [label="Ack()", URL="\ref Ack()", ID="1"]; 2974 * \endmsc 2975 */ 2976class Sender 2977{ 2978 public: 2979 /** Acknowledgment from server */ 2980 void Ack(bool ok); 2981}; 2982 2983/** Receiver class. Can be used to receive and execute commands. 2984 * After execution of a command, the receiver will send an acknowledgment 2985 * \msc 2986 * Receiver,Sender; 2987 * Receiver<-Sender [label="Command()", URL="\ref Command()"]; 2988 * Receiver->Sender [label="Ack()", URL="\ref Sender::Ack()", ID="1"]; 2989 * \endmsc 2990 */ 2991class Receiver 2992{ 2993 public: 2994 /** Executable a command on the server */ 2995 void Command(int commandId); 2996}; 2997 2998\endcode 2999 3000 \sa section \ref cmdmscfile "\\mscfile". 3001 3002<hr> 3003\section cmdstartuml \\startuml ['{'option[,option]'}'] ["caption"] [<sizeindication>=<size>] 3004 3005 \addindex \\startuml 3006 3007 Starts a text fragment which should contain a valid description of a 3008 PlantUML diagram. See https://plantuml.com/ for examples. 3009 The text fragment ends with \ref cmdenduml "\\enduml". 3010 \note You need to install Java and the PlantUML's jar file, 3011 if you want to use this command. When using PlantUML in \LaTeX you have to download 3012 some more `jar` files, for details see the PlantUML documentation. 3013 This also is valid for the `<engine>`s `latex` and `math`. 3014 The location of the PlantUML file should be specified using 3015 \ref cfg_plantuml_jar_path "PLANTUML_JAR_PATH". The other jar files should also reside 3016 in this directory. 3017 \note The use of the `<engine>` `ditaa` is not possible in \LaTeX as PlantUML only 3018 supports the `png` format and doxygen requires, temporary, `eps` output. 3019 3020 Not all diagrams can be created with the PlantUML `@startuml` command but need another 3021 PlantUML `@start...` command. This will look like `@start<engine>` where currently supported are 3022 the following `<engine>`s: `uml`, `bpm`, `wire`, `dot`, `ditaa`, `salt`, `math`, `latex`, 3023 `gantt`, `mindmap`, `wbs`, `yaml`, `creole`, `json`, `flow`, `board` and `git`. 3024 By default the `<engine>` is `uml`. The `<engine>` can be specified as an option. 3025 Also the file to write the resulting image to can be specified by means of an option, see the 3026 description of the first (optional) argument for details. 3027 Of course only one `<engine>` can be specified and also the filename can only be specified once. 3028 3029 The first argument is optional and is for compatibility with running PlantUML as a preprocessing 3030 step before running doxygen, you can also add the name of the image file after `\startuml` 3031 and inside curly brackets as option, i.e. 3032 \verbatim 3033 @startuml{myimage.png} "Image Caption" width=5cm 3034 Alice -> Bob : Hello 3035 @enduml 3036 \endverbatim 3037 When the name of the image is specified, doxygen will generate an image with that name. 3038 Without the name doxygen will choose a name automatically. 3039 3040 The second argument is optional and can be used to specify the caption 3041 that is displayed below the image. This argument has to be specified 3042 between quotes even if it does not contain any spaces. The quotes are 3043 stripped before the caption is displayed. 3044 3045 The third argument is also optional and can be used to specify the 3046 width or height of the image. 3047 For a description of the possibilities see the paragraph 3048 \ref image_sizeindicator "Size indication" with the 3049 \ref cmdimage "\\image" command. 3050 3051 \note doxygen creates a temporary file that is automatically removed unless 3052 the \ref cfg_dot_cleanup "DOT_CLEANUP" tag is set to `NO`. 3053 3054Here is an example of the use of the \c \\startuml command. 3055\code 3056/** Sender class. Can be used to send a command to the server. 3057 * The receiver will acknowledge the command by calling Ack(). 3058 * \startuml 3059 * Sender->Receiver : Command() 3060 * Sender<--Receiver : Ack() 3061 * \enduml 3062 */ 3063class Sender 3064{ 3065 public: 3066 /** Acknowledgment from server */ 3067 void Ack(bool ok); 3068}; 3069 3070/** Receiver class. Can be used to receive and execute commands. 3071 * After execution of a command, the receiver will send an acknowledgment 3072 * \startuml 3073 * Receiver<-Sender : Command() 3074 * Receiver-->Sender : Ack() 3075 * \enduml 3076 */ 3077class Receiver 3078{ 3079 public: 3080 /** Executable a command on the server */ 3081 void Command(int commandId); 3082}; 3083\endcode 3084 3085<hr> 3086\section cmddotfile \\dotfile <file> ["caption"] [<sizeindication>=<size>] 3087 3088 \addindex \\dotfile 3089 Inserts an image generated by dot from \<file\> into the documentation. 3090 3091 The first argument specifies the file name of the image. 3092 doxygen will look for files in the paths (or files) that you specified 3093 after the \ref cfg_dotfile_dirs "DOTFILE_DIRS" tag. 3094 If the dot file is found it will be used as an input file to the dot tool. 3095 The resulting image will be put into the correct output directory. 3096 If the dot file name contains spaces you'll have to put quotes ("...") around it. 3097 3098 The second argument is optional and can be used to specify the caption 3099 that is displayed below the image. This argument has to be specified 3100 between quotes even if it does not contain any spaces. The quotes are 3101 stripped before the caption is displayed. 3102 3103 The third argument is also optional and can be used to specify the 3104 width or height of the image. 3105 For a description of the possibilities see the paragraph 3106 \ref image_sizeindicator "Size indication" with the 3107 \ref cmdimage "\\image" command. 3108 3109 \note usage of this command requires that \ref cfg_have_dot "HAVE_DOT" is set to \c YES 3110 3111 \sa section \ref cmddot "\\dot". 3112 3113<hr> 3114\section cmdmscfile \\mscfile <file> ["caption"] [<sizeindication>=<size>] 3115 3116 \addindex \\mscfile 3117 Inserts an image generated by mscgen from \<file\> into the documentation. 3118 See http://www.mcternan.me.uk/mscgen/ for examples. 3119 3120 The first argument specifies the file name of the image. 3121 doxygen will look for files in the paths (or files) that you specified 3122 after the \ref cfg_mscfile_dirs "MSCFILE_DIRS" tag. 3123 If the msc file is found it will be used as an input file to the built in mscgen tool. 3124 The resulting image will be put into the correct output directory. 3125 If the msc file name contains spaces you'll have to put quotes ("...") around it. 3126 3127 The second argument is optional and can be used to specify the caption 3128 that is displayed below the image. This argument has to be specified 3129 between quotes even if it does not contain any spaces. The quotes are 3130 stripped before the caption is displayed. 3131 3132 The third argument is also optional and can be used to specify the 3133 width or height of the image. 3134 For a description of the possibilities see the paragraph 3135 \ref image_sizeindicator "Size indication" with the 3136 \ref cmdimage "\\image" command. 3137 3138 \note The text fragment should include the part message of the 3139 sequence chart as well as the starting `msc {` and ending `}` 3140 (this is different from \ref cmdmsc "\\msc"). 3141 3142 \sa section \ref cmdmsc "\\msc". 3143 3144<hr> 3145\section cmddiafile \\diafile <file> ["caption"] [<sizeindication>=<size>] 3146 3147 \addindex \\diafile 3148 Inserts an image made in dia from \<file\> into the documentation. 3149 3150 The first argument specifies the file name of the image. 3151 doxygen will look for files in the paths (or files) that you specified 3152 after the \ref cfg_diafile_dirs "DIAFILE_DIRS" tag. 3153 If the dia file is found it will be used as an input file dia. 3154 The resulting image will be put into the correct output directory. 3155 If the dia file name contains spaces you'll have to put quotes ("...") around it. 3156 3157 The second argument is optional and can be used to specify the caption 3158 that is displayed below the image. This argument has to be specified 3159 between quotes even if it does not contain any spaces. The quotes are 3160 stripped before the caption is displayed. 3161 3162 The third argument is also optional and can be used to specify the 3163 width or height of the image. 3164 For a description of the possibilities see the paragraph 3165 \ref image_sizeindicator "Size indication" with the 3166 \ref cmdimage "\\image" command. 3167 3168<hr> 3169\section cmde \\e <word> 3170 3171 \addindex \\e 3172 Displays the argument \<word\> in italics. 3173 Use this command to emphasize words. 3174 3175 \par Example: 3176 Typing: 3177 \verbatim 3178 ... this is a \e really good example ... 3179 \endverbatim 3180 will result in the following text:<br><br> 3181 ... this is a \e really good example ... 3182 3183 Equivalent to \ref cmda "\\a" and \ref cmdem "\\em". 3184 To emphasize multiple words use \ref htmltag_EM "\<em\>"multiple words\ref htmltag_endEM "\</em\>". 3185 3186<hr> 3187\section cmdem \\em <word> 3188 3189 \addindex \\em 3190 Displays the argument \<word\> in italics. 3191 Use this command to emphasize words. 3192 3193 \par Example: 3194 Typing: 3195 \verbatim 3196 ... this is a \em really good example ... 3197 \endverbatim 3198 will result in the following text:<br><br> 3199 ... this is a \em really good example ... 3200 3201 Equivalent to \ref cmda "\\a" and \ref cmde "\\e". 3202 To emphasize multiple words use \ref htmltag_EM "\<em\>"multiple words\ref htmltag_endEM "\</em\>". 3203 3204<hr> 3205\section cmdendcode \\endcode 3206 3207 \addindex \\endcode 3208 Ends a block of code. 3209 \sa section \ref cmdcode "\\code" 3210 3211<hr> 3212\section cmdenddocbookonly \\enddocbookonly 3213 3214 \addindex \\enddocbookonly 3215 Ends a block of text that was started with a \ref cmddocbookonly "\\docbookonly" command. 3216 3217 \sa section \ref cmddocbookonly "\\docbookonly". 3218 3219<hr> 3220\section cmdenddot \\enddot 3221 3222 \addindex \\enddot 3223 Ends a block that was started with \ref cmddot "\\dot". 3224 3225<hr> 3226\section cmdendmsc \\endmsc 3227 3228 \addindex \\endmsc 3229 Ends a block that was started with \ref cmdmsc "\\msc". 3230 3231<hr> 3232\section cmdenduml \\enduml 3233 3234 \addindex \\enduml 3235 Ends a block that was started with \ref cmdstartuml "\\startuml". 3236 3237<hr> 3238\section cmdendhtmlonly \\endhtmlonly 3239 3240 \addindex \\endhtmlonly 3241 Ends a block of text that was started with a \ref cmdhtmlonly "\\htmlonly" command. 3242 3243 \sa section \ref cmdhtmlonly "\\htmlonly". 3244 3245<hr> 3246\section cmdendlatexonly \\endlatexonly 3247 3248 \addindex \\endlatexonly 3249 Ends a block of text that was started with a \ref cmdlatexonly "\\latexonly" command. 3250 3251 \sa section \ref cmdlatexonly "\\latexonly". 3252 3253<hr> 3254\section cmdendmanonly \\endmanonly 3255 3256 \addindex \\endmanonly 3257 Ends a block of text that was started with a \ref cmdmanonly "\\manonly" command. 3258 3259 \sa section \ref cmdmanonly "\\manonly". 3260 3261<hr> 3262\section cmdendrtfonly \\endrtfonly 3263 3264 \addindex \\endrtfonly 3265 Ends a block of text that was started with a \ref cmdrtfonly "\\rtfonly" command. 3266 3267 \sa section \ref cmdrtfonly "\\rtfonly". 3268 3269 3270<hr> 3271\section cmdendverbatim \\endverbatim 3272 3273 \addindex \\endverbatim 3274 Ends a block of text that was started with a \ref cmdverbatim "\\verbatim" command. 3275 3276 \sa section \ref cmdverbatim "\\verbatim". 3277 3278<hr> 3279\section cmdendxmlonly \\endxmlonly 3280 3281 \addindex \\endxmlonly 3282 Ends a block of text that was started with a \ref cmdxmlonly "\\xmlonly" command. 3283 3284 \sa section \ref cmdxmlonly "\\xmlonly". 3285 3286<hr> 3287\section cmdfdollar \\f$ 3288 3289 \addindex \\f\$ 3290 3291 Marks the start and end of an in-text formula. 3292 \sa section \ref formulas "formulas" for an example. 3293 3294<hr> 3295\section cmdfrndopen \\f( 3296 3297 \addindex \\f( 3298 3299 Marks the start of an in-text formula, but contrary to \ref cmdfdollar "\\f$" it will 3300 not explicitly open the math-mode in \LaTeX. 3301 \sa section \ref cmdfrndclose "\\f)" and section \ref formulas "formulas". 3302 3303<hr> 3304\section cmdfrndclose \\f) 3305 3306 \addindex \\f) 3307 3308 Marks the end of an in-text formula started with \ref cmdfrndopen "\\f(". 3309 \sa section \ref cmdfrndopen "\\f(" and section \ref formulas "formulas". 3310 3311<hr> 3312\section cmdfbropen \\f[ 3313 3314 \addindex \\f[ 3315 3316 Marks the start of a long formula that is displayed 3317 centered on a separate line. 3318 \sa section \ref cmdfbrclose "\\f]" and section \ref formulas "formulas". 3319 3320<hr> 3321\section cmdfbrclose \\f] 3322 3323 \addindex \\f] 3324 3325 Marks the end of a long formula that is displayed 3326 centered on a separate line. 3327 \sa section \ref cmdfbropen "\\f[" and section \ref formulas "formulas". 3328 3329<hr> 3330\section cmdfcurlyopen \\f{environment}{ 3331 3332 \addindex \\f{ 3333 3334 Marks the start of a formula that is in a specific environment. 3335 \note The second \c { is optional and is only to help editors (such as \c Vim) to 3336 do proper syntax highlighting by making the number of opening and closing braces 3337 the same. 3338 \sa section \ref cmdfcurlyclose "\\f}" and section \ref formulas "formulas". 3339 3340<hr> 3341\section cmdfcurlyclose \\f} 3342 3343 \addindex \\f} 3344 3345 Marks the end of a formula that is in a specific environment. 3346 \sa section \ref cmdfcurlyopen "\\f{" and section \ref formulas "formulas". 3347 3348<hr> 3349\section cmdhtmlonly \\htmlonly ["[block]"] 3350 3351 \addindex \\htmlonly 3352 Starts a block of text that only will be verbatim included in the 3353 generated HTML documentation and tagged with `<htmlonly>` in the generated 3354 XML output. The block ends with a 3355 \ref cmdendhtmlonly "\\endhtmlonly" command. 3356 3357 This command can be used to include HTML code that is too complex 3358 for doxygen (i.e. applets, java-scripts, and HTML tags that 3359 require specific attributes). 3360 3361 Normally the contents between \ref cmdhtmlonly "\\htmlonly" and 3362 \ref cmdendhtmlonly "\\endhtmlonly" is inserted as-is. When you 3363 want to insert a HTML fragment that has block scope like a table or list 3364 which should appear outside \<p\>..\</p\>, this can lead to invalid HTML. 3365 You can use \\htmlonly[block] to make doxygen 3366 end the current paragraph and restart it after \\endhtmlonly. 3367 3368 \note environment variables (like \$(HOME) ) are resolved inside a 3369 HTML-only block. 3370 3371 \sa section \ref cmdmanonly "\\manonly", 3372 \ref cmdlatexonly "\\latexonly", 3373 \ref cmdrtfonly "\\rtfonly", 3374 \ref cmdxmlonly "\\xmlonly", 3375 \ref cmddocbookonly "\\docbookonly", and 3376 \ref cmdhtmlinclude "\\htmlinclude". 3377 3378<hr> 3379\section cmdimage \\image['{'option[,option]'}'] <format> <file> ["caption"] [<sizeindication>=<size>] 3380 3381 \addindex \\image 3382 Inserts an image into the documentation. This command is format 3383 specific, so if you want to insert an image for more than one 3384 format you'll have to repeat this command for each format. 3385 3386 The first argument specifies the output format in which the image should 3387 be embedded. Currently, the following values are supported: 3388 \c html, \c latex, \c docbook, \c rtf and \c xml. 3389 3390 The second argument specifies the file name of the image. 3391 doxygen will look for files in the paths (or files) that you specified 3392 after the \ref cfg_image_path "IMAGE_PATH" tag. 3393 If the image is found it will be copied to the correct output directory. 3394 If the image name contains spaces you'll have to put quotes ("...") around 3395 the name. You can also specify an absolute URL instead of a file name, but then 3396 doxygen does not copy the image nor check its existence. 3397 3398 The third argument is optional and can be used to specify the caption 3399 that is displayed below the image. This argument has to be specified 3400 on a single line and between quotes even if it does not contain any 3401 spaces. The quotes are stripped before the caption is displayed. 3402 3403 The fourth argument is also optional and can be used to specify the 3404 width or height of the image. This can be useful for \LaTeX or DocBook output 3405 (i.e. format=<code>latex</code> or format=<code>docbook</code>). 3406 \anchor image_sizeindicator \par Size indication 3407 The \c sizeindication can specify the width or height to be used (or a combination). 3408 The size specifier in \LaTeX (for example `10cm` or 3409 `4in` or a symbolic width like `\textwidth`). 3410 3411 Currently only the options `inline` and `anchor` are supported. In case the option `inline` is 3412 specified the image is placed "in the line", when a caption s present it is shown 3413 in HTML as tooltip (ignored for the other formats). For the `anchor` option the syntax is: 3414 `anchor:<anchorId>`. 3415 3416 Here is example of a comment block: 3417 3418\verbatim 3419 /*! Here is a snapshot of my new application: 3420 * \image html application.jpg 3421 * \image latex application.eps "My application" width=10cm 3422 */ 3423\endverbatim 3424 3425 And this is an example of how the relevant part of the configuration file 3426 may look: 3427 3428\verbatim 3429 IMAGE_PATH = my_image_dir 3430\endverbatim 3431 3432 \warning The image format for HTML is limited to what your 3433 browser supports.<br>For \LaTeX, the image format 3434 must be supported by the \LaTeX `\includegraphics` command i.e. 3435 Encapsulated PostScript (eps), Portable network graphics (png), 3436 Joint photographic experts group (jpg / jpeg). 3437 <br><br> 3438 Doxygen does not check if the image is in the correct format. 3439 So \e you have to make sure this is the case! 3440 3441<hr> 3442\section cmdlatexonly \\latexonly 3443 3444 \addindex \\latexonly 3445 Starts a block of text that only will be verbatim included in the 3446 generated \LaTeX documentation and tagged with `<latexonly>` in the generated 3447 XML output. The block ends with a 3448 \ref cmdendlatexonly "\\endlatexonly" command. 3449 3450 This command can be used to include \LaTeX code that is too 3451 complex for doxygen (i.e. images, formulas, special characters). You can 3452 use the \ref cmdhtmlonly "\\htmlonly" and \ref cmdendhtmlonly "\\endhtmlonly" 3453 pair to provide a proper HTML alternative. 3454 3455 \b Note: 3456 environment variables (like \$(HOME) ) are resolved inside a 3457 \LaTeX-only block. 3458 3459 \sa sections \ref cmdrtfonly "\\rtfonly", 3460 \ref cmdxmlonly "\\xmlonly", 3461 \ref cmdmanonly "\\manonly", 3462 \ref cmdhtmlonly "\\htmlonly", 3463 \ref cmddocbookonly "\\docbookonly", and 3464 \ref cmdlatexinclude "\\latexinclude". 3465 3466<hr> 3467\section cmdmanonly \\manonly 3468 3469 \addindex \\manonly 3470 Starts a block of text that only will be verbatim included in the 3471 generated MAN documentation and tagged with `<manonly>` in the generated 3472 XML output. The block ends with a 3473 \ref cmdendmanonly "\\endmanonly" command. 3474 3475 This command can be used to include groff code directly into 3476 MAN pages. You can use the \ref cmdhtmlonly "\\htmlonly" and 3477 \ref cmdendhtmlonly "\\endhtmlonly" and 3478 \ref cmdlatexonly "\\latexonly" and 3479 \ref cmdendlatexonly "\\endlatexonly" pairs to provide proper 3480 HTML and \LaTeX alternatives. 3481 3482 \sa sections \ref cmdhtmlonly "\\htmlonly", 3483 \ref cmdxmlonly "\\xmlonly", 3484 \ref cmdrtfonly "\\rtfonly", 3485 \ref cmdlatexonly "\\latexonly", 3486 \ref cmddocbookonly "\\docbookonly" and 3487 \ref cmdmaninclude "\\maninclude". 3488 3489<hr> 3490\section cmdli \\li { item-description } 3491 3492 \addindex \\li 3493 This command has one argument that continues until the first 3494 blank line or until another \c \\li is encountered. 3495 The command can be used to generate a simple, not nested list of 3496 arguments. 3497 Each argument should start with a \c \\li command. 3498 3499 \par Example: 3500 Typing: 3501 \verbatim 3502 \li \c AlignLeft left alignment. 3503 \li \c AlignCenter center alignment. 3504 \li \c AlignRight right alignment 3505 3506 No other types of alignment are supported. 3507 \endverbatim 3508 will result in the following text:<br><br> 3509 <ul> 3510 <li> \c AlignLeft left alignment. 3511 <li> \c AlignCenter center alignment. 3512 <li> \c AlignRight right alignment 3513 </ul><br> 3514 No other types of alignment are supported. 3515 3516 \par Note: 3517 For nested lists, HTML commands should be used. 3518 3519 Equivalent to \ref cmdarg "\\arg" 3520 3521<hr> 3522\section cmdn \\n 3523 3524 \addindex \\n 3525 Forces a new line. Equivalent to \ref htmltag_BR "\<br\>" and inspired by 3526 the \c printf function. 3527 3528<hr> 3529\section cmdp \\p <word> 3530 3531 \addindex \\p 3532 Displays the parameter \<word\> using a typewriter font. 3533 You can use this command to refer to member function parameters in 3534 the running text. 3535 3536 \par Example: 3537 \verbatim 3538 ... the \p x and \p y coordinates are used to ... 3539 \endverbatim 3540 This will result in the following text:<br><br> 3541 ... the \p x and \p y coordinates are used to ... 3542 3543 Equivalent to \ref cmdc "\\c" 3544 To have multiple words in typewriter font use \ref htmltag_TT "\<tt\>"multiple words\ref htmltag_endTT "\</tt\>". 3545 3546<hr> 3547\section cmdrtfonly \\rtfonly 3548 3549 \addindex \\rtfonly 3550 Starts a block of text that only will be verbatim included in the 3551 generated RTF documentation and tagged with `<rtfonly>` in the generated 3552 XML output. The block ends with a 3553 \ref cmdendrtfonly "\\endrtfonly" command. 3554 3555 This command can be used to include RTF code that is too complex 3556 for doxygen. 3557 3558 \b Note: 3559 environment variables (like \$(HOME) ) are resolved inside a 3560 RTF-only block. 3561 3562 \sa sections \ref cmdmanonly "\\manonly", 3563 \ref cmdxmlonly "\\xmlonly", 3564 \ref cmdlatexonly "\\latexonly", 3565 \ref cmdhtmlonly "\\htmlonly", 3566 \ref cmddocbookonly "\\docbookonly" and 3567 \ref cmdrtfinclude "\\rtfinclude". 3568 3569<hr> 3570\section cmdverbatim \\verbatim 3571 3572 \addindex \\verbatim 3573 Starts a block of text that will be verbatim included in 3574 the documentation. The block should end with a 3575 \ref cmdendverbatim "\\endverbatim" command. 3576 All commands are disabled in a verbatim block. 3577 3578 \warning Make sure you include a \ref cmdendverbatim "\\endverbatim" command for each 3579 \c \\verbatim command or the parser will get confused! 3580 3581 \sa sections \ref cmdcode "\\code", 3582 \ref cmdendverbatim "\\endverbatim" and 3583 \ref cmdverbinclude "\\verbinclude". 3584 3585<hr> 3586\section cmdxmlonly \\xmlonly 3587 3588 \addindex \\xmlonly 3589 Starts a block of text that only will be verbatim included in the 3590 generated XML output. The block ends with a 3591 \ref cmdendxmlonly "\\endxmlonly" command. 3592 3593 This command can be used to include custom XML tags. 3594 3595 \sa sections \ref cmdmanonly "\\manonly", 3596 \ref cmdrtfonly "\\rtfonly", 3597 \ref cmdlatexonly "\\latexonly", 3598 \ref cmdhtmlonly "\\htmlonly", and 3599 \ref cmddocbookonly "\\docbookonly". 3600 3601<hr> 3602\section cmdbackslash \\\\ 3603 3604 \addindex \\\\ 3605 This command writes a backslash character (\c \\) to the 3606 output. The backslash has to be escaped in some 3607 cases because doxygen uses it to detect commands. 3608 3609<hr> 3610\section cmdat \\\@ 3611 3612 \addindex \\\@ 3613 This command writes an at-sign (\c \@) to the output. 3614 The at-sign has to be escaped in some cases 3615 because doxygen uses it to detect Javadoc commands. 3616 3617<hr> 3618\section cmdtilde \\~[LanguageId] 3619 \addindex \\~ 3620 This command enables/disables a language specific filter. This can be 3621 used to put documentation for different language into one comment block 3622 and use the \ref cfg_output_language "OUTPUT_LANGUAGE" tag to filter out only a specific language. 3623 Use \c \\~language_id to enable output for a specific language only and 3624 \c \\~ to enable output for all languages (this is also the default mode). 3625 3626 Example: 3627\verbatim 3628/*! \~english This is English \~dutch Dit is Nederlands \~german Dies ist 3629 Deutsch. \~ output for all languages. 3630 */ 3631\endverbatim 3632 3633 3634<hr> 3635\section cmdamp \\\& 3636 3637 \addindex \\\& 3638 This command writes the \c \& character to the output. 3639 This character has to be escaped because it has a special meaning in HTML. 3640 3641<hr> 3642\section cmddollar \\\$ 3643 3644 \addindex \\\$ 3645 This command writes the \c \$ character to the output. 3646 This character has to be escaped in some cases, because it is used to expand 3647 environment variables. 3648 3649<hr> 3650\section cmdhash \\\# 3651 3652 \addindex \\\# 3653 This command writes the \c \# character to the output. This 3654 character has to be escaped in some cases, because it is used to refer 3655 to documented entities. 3656 3657<hr> 3658\section cmdlt \\\< 3659 3660 \addindex \\\< 3661 This command writes the \c \< character to the output. 3662 This character has to be escaped because it has a special meaning in HTML. 3663 3664<hr> 3665\section cmdgt \\\> 3666 3667 \addindex \\\> 3668 This command writes the \c \> character to the output. This 3669 character has to be escaped because it has a special meaning in HTML. 3670 3671<hr> 3672\section cmdperc \\\% 3673 3674 \addindex \\\% 3675 This command writes the \c \% character to the output. This 3676 character has to be escaped in some cases, because it is used to 3677 prevent auto-linking to a word that is also a documented class or struct. 3678 3679<hr> 3680\section cmdquot \\" 3681 3682 \addindex \\\" 3683 This command writes the \c \" character to the output. This 3684 character has to be escaped in some cases, because it is used in pairs 3685 to indicate an unformatted text fragment. 3686 3687<hr> 3688\section cmdchardot \\. 3689 3690 \addindex \\\. 3691 This command writes a dot (`.`) to the output. This can be useful to 3692 prevent ending a brief description when \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" is enabled 3693 or to prevent starting a numbered list when the dot follows a number at 3694 the start of a line. 3695 3696<hr> 3697\section cmdeq \\= 3698 3699 \addindex \\= 3700 This command writes an equal sign (`=`) to the output. This 3701 character sequence has to be escaped in some cases, because it is used 3702 in Markdown header processing. 3703 3704<hr> 3705\section cmddcolon \\:: 3706 3707 \addindex \\:: 3708 This command writes a double colon (\c \::) to the output. This 3709 character sequence has to be escaped in some cases, because it is used 3710 to reference to documented entities. 3711 3712<hr> 3713\section cmdpipe \\| 3714 3715 \addindex \\| 3716 This command writes a pipe symbol (\|) to the output. This 3717 character has to be escaped in some cases, because it is used 3718 for Markdown tables. 3719 3720<hr> 3721\section cmdndash \\-- 3722 3723 \addindex \\\-- 3724 This command writes two dashes (\--) to the output. This allows 3725 writing two consecutive dashes to the output instead of one n-dash character (--). 3726 3727<hr> 3728\section cmdmdash \\--- 3729 3730 \addindex \\\--- 3731 This command writes three dashes (\---) to the output. This allows 3732 writing three consecutive dashes to the output instead of one m-dash character (---). 3733 3734<hr> 3735\htmlonly</p><center><p>\endhtmlonly 3736<h2> 3737\htmlonly --- \endhtmlonly 3738Commands included for Qt compatibility 3739\htmlonly --- \endhtmlonly 3740</h2> 3741\htmlonly</p></center><p>\endhtmlonly 3742 3743The following commands are supported to remain compatible to the Qt class 3744browser generator. Do \e not use these commands in your own documentation. 3745<ul> 3746<li>\\annotatedclasslist 3747<li>\\classhierarchy 3748<li>\\define 3749<li>\\functionindex 3750<li>\\header 3751<li>\\headerfilelist 3752<li>\\inherit 3753<li>\\l 3754<li>\\postheader 3755</ul> 3756<hr> 3757 3758 3759\htmlonly 3760Go to the <a href="htmlcmds.html">next</a> section or return to the 3761 <a href="index.html">index</a>. 3762\endhtmlonly 3763 3764*/ 3765