/******************************************************************************

 *

 * 

 *

 * Copyright (C) 1997-2008 by Dimitri van Heesch.

 *

 * Permission to use, copy, modify, and distribute this software and its

 * documentation under the terms of the GNU General Public License is hereby 

 * granted. No representations are made about the suitability of this software 

 * for any purpose. It is provided "as is" without express or implied warranty.

 * See the GNU General Public License for more details.

 *

 * Documents produced by Doxygen are derivative works derived from the

 * input used in their production; they are not affected by this license.

 *

 */

/*! \page commands Special Commands

\section cmd_intro Introduction

All commands in the documentation start with a backslash (<b>\\</b>) or an

at-sign (<b>\@</b>). If you prefer you can replace all commands starting with a 

backslash below by their counterparts that start with an at-sign.

Some commands have one or more arguments. 

Each argument has a certain range:

<ul>

<li>If \<sharp\> braces are used the argument is a single word.

<li>If (round) braces are used the argument extends until the end of the line

    on which the command was found.

<li>If {curly} braces are used the argument extends until the next paragraph.

    Paragraphs are delimited by a blank line or by a section indicator.

</ul>

If [square] brackets are used the argument is optional.

Here is an alphabetically sorted list of all commands with references to their 

documentation:

\secreflist

\refitem cmda \\a

\refitem cmdaddindex \\addindex

\refitem cmdaddtogroup \\addtogroup

\refitem cmdanchor \\anchor

\refitem cmdarg \\arg

\refitem cmdattention \\attention

\refitem cmdauthor \\author

\refitem cmdb \\b

\refitem cmdbrief \\brief

\refitem cmdbug \\bug

\refitem cmdc \\c

\refitem cmdcallgraph \\callgraph

\refitem cmdcallergraph \\callergraph

\refitem cmdcategory \\category

\refitem cmdclass \\class

\refitem cmdcode \\code

\refitem cmdcond \\cond

\refitem cmdcopybrief \\copybrief

\refitem cmdcopydetails \\copydetails

\refitem cmdcopydoc \\copydoc

\refitem cmddate \\date

\refitem cmddef \\def

\refitem cmddefgroup \\defgroup

\refitem cmddeprecated \\deprecated

\refitem cmddetails \\details

\refitem cmddir \\dir

\refitem cmddontinclude \\dontinclude

\refitem cmddot \\dot

\refitem cmddotfile \\dotfile

\refitem cmde \\e

\refitem cmdelse \\else

\refitem cmdelseif \\elseif

\refitem cmdem \\em

\refitem cmdendcode \\endcode

\refitem cmdendcond \\endcond

\refitem cmdenddot \\enddot

\refitem cmdendhtmlonly \\endhtmlonly

\refitem cmdendif \\endif

\refitem cmdendlatexonly \\endlatexonly

\refitem cmdendlink \\endlink

\refitem cmdendmanonly \\endmanonly

\refitem cmdendmsc \\endmsc

\refitem cmdendverbatim \\endverbatim

\refitem cmdendxmlonly \\endxmlonly

\refitem cmdenum \\enum

\refitem cmdexample \\example

\refitem cmdexception \\exception

\refitem cmdextends \\extends

\refitem cmdfdollar \\f\$

\refitem cmdfbropen \\f[

\refitem cmdfbrclose \\f]

\refitem cmdfcurlyopen \\f{

\refitem cmdfcurlyclose \\f}

\refitem cmdfile \\file

\refitem cmdfn \\fn

\refitem cmdheaderfile \\headerfile

\refitem cmdhideinitializer \\hideinitializer

\refitem cmdhtmlinclude \\htmlinclude

\refitem cmdhtmlonly \\htmlonly

\refitem cmdif \\if

\refitem cmdifnot \\ifnot

\refitem cmdimage \\image

\refitem cmdimplements \\implements

\refitem cmdinclude \\include

\refitem cmdincludelineno \\includelineno

\refitem cmdingroup \\ingroup

\refitem cmdinternal \\internal

\refitem cmdinvariant \\invariant

\refitem cmdinterface \\interface

\refitem cmdlatexonly \\latexonly

\refitem cmdli \\li

\refitem cmdline \\line

\refitem cmdlink \\link

\refitem cmdmainpage \\mainpage

\refitem cmdmanonly \\manonly

\refitem cmdmemberof \\memberof

\refitem cmdmsc \\msc

\refitem cmdn \\n

\refitem cmdname \\name

\refitem cmdnamespace \\namespace

\refitem cmdnosubgrouping \\nosubgrouping

\refitem cmdnote \\note

\refitem cmdoverload \\overload

\refitem cmdp \\p

\refitem cmdpackage \\package

\refitem cmdpage \\page

\refitem cmdpar \\par

\refitem cmdparagraph \\paragraph

\refitem cmdparam \\param

\refitem cmdpost \\post

\refitem cmdpre \\pre

\refitem cmdprivate \\private

\refitem cmdprivate \\privatesection

\refitem cmdproperty \\property

\refitem cmdprotected \\protected

\refitem cmdprotected \\protectedsection

\refitem cmdprotocol \\protocol

\refitem cmdpublic \\public

\refitem cmdpublic \\publicsection

\refitem cmdref \\ref

\refitem cmdrelates \\relates

\refitem cmdrelatesalso \\relatesalso

\refitem cmdremarks \\remarks

\refitem cmdreturn \\return

\refitem cmdretval \\retval

\refitem cmdsa \\sa

\refitem cmdsection \\section

\refitem cmdsee \\see

\refitem cmdshowinitializer \\showinitializer

\refitem cmdsince \\since

\refitem cmdskip \\skip

\refitem cmdskipline \\skipline

\refitem cmdstruct \\struct

\refitem cmdsubpage \\subpage

\refitem cmdsubsection \\subsection

\refitem cmdsubsubsection \\subsubsection

\refitem cmdtest \\test

\refitem cmdthrow \\throw

\refitem cmdtodo \\todo

\refitem cmdtparam \\tparam

\refitem cmdtypedef \\typedef

\refitem cmdunion \\union

\refitem cmduntil \\until

\refitem cmdvar \\var

\refitem cmdverbatim \\verbatim

\refitem cmdverbinclude \\verbinclude

\refitem cmdversion \\version

\refitem cmdwarning \\warning

\refitem cmdweakgroup \\weakgroup

\refitem cmdxmlonly \\xmlonly

\refitem cmdxrefitem \\xrefitem

\refitem cmddollar \\\$

\refitem cmdat \\\@

\refitem cmdbackslash \\\\

\refitem cmdamp \\\&

\refitem cmdtilde \\~

\refitem cmdlt \\\<

\refitem cmdgt \\\>

\refitem cmdhash \\\#

\refitem cmdperc \\\%

\refitem cmdquot \\\"

\endsecreflist

The following subsections provide a list of all commands that are recognized by

doxygen. Unrecognized commands are treated as normal text.

\htmlonly <center> \endhtmlonly 

<h2>

\htmlonly --- \endhtmlonly 

Structural indicators

\htmlonly --- \endhtmlonly 

</h2>

\htmlonly </center> \endhtmlonly

\section cmdaddtogroup \\addtogroup <name> [(title)]

  \addindex \\addtogroup

  Defines a group just like \ref cmddefgroup "\\defgroup", but in contrast to

  that command using the same \<name\> more than once will not result in a warning,

  but rather one group with a merged documentation and the first title found in

  any of the commands.

  The title is optional, so this command can also be used to add a number of 

  entities to an existing group using \@{ and \@} like this:

\verbatim

  /*! \addtogroup mygrp

   *  Additional documentation for group `mygrp'

   *  @{

   */

  /*!

   *  A function 

   */

  void func1()

  {

  }

  /*! Another function */

  void func2()

  {

  }

  /*! @} */

\endverbatim

  \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup", \ref cmdingroup "\\ingroup" and

  \ref cmdweakgroup "\\weakgroup".

<hr>

\section cmdcallgraph \\callgraph 

  \addindex \\callgraph

  When this command is put in a comment block of a function or method

  and \ref cfg_have_dot "HAVE_DOT" is set to YES, then doxygen will 

  generate a call graph for that function (provided the implementation of the

  function or method calls other documented functions). The call graph will 

  generated regardless of the value of \ref cfg_call_graph "CALL_GRAPH".

  \note The completeness (and correctness) of the call graph depends on the 

  doxygen code parser which is not perfect.

<hr>

\section cmdcallergraph \\callergraph 

  \addindex \\callergraph

  When this command is put in a comment block of a function or method

  and \ref cfg_have_dot "HAVE_DOT" is set to YES, then doxygen will 

  generate a caller graph for that function (provided the implementation of the

  function or method calls other documented functions). The caller graph will 

  generated regardless of the value of \ref cfg_caller_graph "CALLER_GRAPH".

  \note The completeness (and correctness) of the caller graph depends on the 

  doxygen code parser which is not perfect.

<hr>

\section cmdcategory \\category <name> [<header-file>] [<header-name>]

  \addindex \\category

  For Objective-C only: Indicates that a comment block contains documentation 

  for a class category with name \<name\>. The arguments are 

  equal to the \\class command.

  \sa section \ref cmdclass "\\class".

<hr>

\section cmdclass \\class <name> [<header-file>] [<header-name>]

  \addindex \\class

  Indicates that a comment block contains documentation for a

  class with name \<name\>. Optionally a header file and a header name 

  can be specified. If the header-file is specified, a link to a verbatim copy 

  of the header will be included in the HTML documentation. 

  The \<header-name\> argument can be used to overwrite the 

  name of the link that is used in the class documentation to something other 

  than \<header-file\>. This can be useful if the include name is not located 

  on the default include path (like \<X11/X.h\>). With the \<header-name\>

  argument you can also specify how the include statement should look like, 

  by adding either quotes or sharp brackets around the name. 

  Sharp brackets are used if just the name is given. Note that the 

  last two arguments can also specified using 

  the \ref cmdheaderfile "\\headerfile" command.

  \par Example: 

  \verbinclude class.h  

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/class/html/index.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

<hr>

\section cmddef \\def <name>

  \addindex \\def

  Indicates that a comment block contains documentation for a 

  \c \#define macro. 

  \par Example:

  \verbinclude define.h  

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/define/html/define_8h.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

<hr>

\section cmddefgroup \\defgroup <name> (group title)

  \addindex \\defgroup

  Indicates that a comment block contains documentation for a

  \ref modules "group" of classes, files or namespaces. This can be used to

  categorize classes, files or namespaces, and document those

  categories. You can also use groups as members of other groups,

  thus building a hierarchy of groups.

  The \<name\> argument should be a single-word identifier.

  \sa page \ref grouping "Grouping", sections \ref cmdingroup "\\ingroup", \ref cmdaddtogroup "\\addtogroup",

  \ref cmdweakgroup "\\weakgroup".

<hr>

\section cmddir \\dir [<path fragment>]

  \addindex \\dir

  Indicates that a comment block contains documentation for a directory.

  The "path fragment" argument should include the directory name and 

  enough of the path to be unique w.r.t. the other directories in the project.

  The \ref cfg_show_dirs "SHOW_DIRECTORIES" option determines whether 

  or not the directory information is shown and the

  \ref cfg_strip_from_path "STRIP_FROM_PATH" option determines what is 

  stripped from the full path before it appears in the output.

<hr>

\section cmdenum \\enum <name>

  \addindex \\enum

  Indicates that a comment block contains documentation for an 

  enumeration, with name \<name\>. If the enum is a member of a class and

  the documentation block is located outside the class definition,

  the scope of the class should be specified as well.

  If a comment block is located directly in front of an enum declaration,

  the \\enum comment may be omitted.

  \par Note:

  The type of an anonymous enum cannot be documented, but the values 

  of an anonymous enum can.

  \par Example:

  \verbinclude enum.h  

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/enum/html/class_test.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

<hr>

\section cmdexample \\example <file-name>

  \addindex \\example

  Indicates that a comment block contains documentation for a source code 

  example. The name of the source file is \<file-name\>. The text of

  this file will be included in the documentation, just after the 

  documentation contained in the comment block. All examples are placed

  in a list. The source code is scanned for documented members and classes.

  If any are found, the names are cross-referenced with the documentation. 

  Source files or directories can be specified using the 

  \ref cfg_example_path "EXAMPLE_PATH" 

  tag of doxygen's configuration file.

  If \<file-name\> itself is not unique for the set of example files specified

  by the 

  \ref cfg_example_path "EXAMPLE_PATH" tag, you can include part of the absolute path

  to disambiguate it.

  If more that one source file is needed for the example,

  the \\include command can be used.

  \par Example:

  \verbinclude example.cpp

  Where the example file \c example_test.cpp looks as follows:

  \verbinclude example_test.cpp

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/example/html/examples.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

  \sa section \ref cmdinclude "\\include".

<hr>

\section cmdextends \\extends <name>

  \addindex \\extends

  This command can be used to manually indicate an inheritance relation,

  when the programming language does not support this concept natively

  (e.g. C).

  The file \c manual.c in the example directory shows how to use this command.

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

  \sa section \ref cmdimplements "\\implements" and section

      \ref cmdmemberof "\\memberof"

<hr>

\section cmdfile \\file [<name>]

  \addindex \\file

  Indicates that a comment block contains documentation for a source or 

  header file with name \<name\>. The file name may include (part of) the

  path if the file-name alone is not unique. If the file name is omitted

  (i.e. the line after \\file is left blank) then the documentation block that 

  contains the \\file command will belong to the file it is located in.

  \par Important:

  The documentation of global functions, variables, typedefs, and enums will 

  only be included in the output if the file they are in is documented as well.

  \par Example:

  \verbinclude file.h  

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/file/html/file_8h.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

  \note In the above example \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF"

  has been set to YES in the configuration file.

<hr>

\section cmdfn \\fn (function declaration)

  \addindex \\fn

  Indicates that a comment block contains documentation for a function

  (either global or as a member of a class). This command is \em only 

  needed if a comment block is \e not placed in front (or behind) 

  the function declaration or definition. 

  If your comment block \e is in front of the function 

  declaration or definition this command can (and to avoid redundancy

  should) be omitted. 

  A full function declaration including arguments should be specified after the

  \\fn command on a \e single line, since the argument ends at the end 

  of the line!

  \warning Do not use this command

  if it is not absolutely needed, since it will lead to duplication of 

  information and thus to errors.

  \par Example:

  \verbinclude func.h  

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/func/html/class_test.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

  \sa section \ref cmdvar "\\var" and \ref cmdtypedef "\\typedef".

<hr>

\section cmdheaderfile \\headerfile <header-file> [<header-name>]

  \addindex \\headerfile

  Intended to be used for class, struct, or union documentation, where

  the documentation is in front of the definition. The arguments of

  this command are the same as the second and third argument of 

  \ref cmdclass "\\cmdclass".

  The header-file name refers to the file that should by included by the 

  application to obtain the definition of the class, struct, or union.

  The \<header-name\> argument can be used to overwrite the 

  name of the link that is used in the class documentation to something other 

  than \<header-file\>. This can be useful if the include name is not located 

  on the default include path (like \<X11/X.h\>). 

  With the \<header-name\>

  argument you can also specify how the include statement should look like, 

  by adding either double quotes or sharp brackets around the name. 

  By default sharp brackets are used if just the name is given. 

  If a pair of double quotes is given for either the header-file or 

  header-name argument, the current file (in which the command was found) 

  will be used but with quotes. So for a comment block with a \\headerfile

  command inside a file test.h, the following three commands are equivalent:

  \verbatim

  \headerfile test.h "test.h"

  \headerfile test.h ""

  \headerfile "" \endverbatim

  To get sharp brackets you do not need to specify anything,

  but if you want to be explicit you could use any of the following:

  \verbatim

  \headerfile test.h <test.h>

  \headerfile test.h <>

  \headerfile <> \endverbatim

  To globally reverse the default include representation to 

  local includes you can set

  \ref cfg_force_local_includes "FORCE_LOCAL_INCLUDES" to \c YES.

  To disable the include information altogether set

  \ref cfg_show_include_files "SHOW_INCLUDE_FILES" to \c NO.

<hr>

\section cmdhideinitializer \\hideinitializer

  \addindex \\hideinitializer

  By default the value of a define and the initializer of a variable

  are displayed unless they are longer than 30 lines. By putting

  this command in a comment block of a define or variable, the 

  initializer is always hidden.

  \sa section \ref cmdshowinitializer "\\showinitializer".

<hr>

\section cmdimplements \\implements <name>

  \addindex \\implements

  This command can be used to manually indicate an inheritance relation,

  when the programming language does not support this concept natively

  (e.g. C).

  The file \c manual.c in the example directory shows how to use this command.

  \htmlonly

  Click <a href="$(DOXYGEN_DOCDIR)/examples/manual/html/index.html">here</a> 

  for the corresponding HTML documentation that is generated by doxygen.

  \endhtmlonly

  \sa section \ref cmdextends "\\extends" and section

      \ref cmdmemberof "\\memberof"

<hr>

\section cmdingroup \\ingroup (<groupname> [<groupname> <groupname>])