commands.doc

doxygen(一个自动从源代码生成文档的工具)的源代码

/******************************************************************************
 *
 * $Id: commands.doc,v 1.17 2001/03/19 19:27:39 root Exp $
 *
 * Copyright (C) 1997-2001 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

\section commands Special Commands

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:
\htmlonly
<multicol cols=4>
<ul>
\endhtmlonly
\latexonly
\begin{multicols}{3}
\begin{CompactList}
\endlatexonly
<li> \refitem cmda \a
<li> \refitem cmdaddindex \addindex
<li> \refitem cmdaddtogroup \addtogroup
<li> \refitem cmdanchor \anchor
<li> \refitem cmdarg \arg
<li> \refitem cmdattention \attention
<li> \refitem cmdauthor \author
<li> \refitem cmdb \b
<li> \refitem cmdbrief \brief
<li> \refitem cmdbug \bug
<li> \refitem cmdc \c
<li> \refitem cmdclass \class
<li> \refitem cmdcode \code
<li> \refitem cmddate \date
<li> \refitem cmddef \def
<li> \refitem cmddefgroup \defgroup
<li> \refitem cmddeprecated \deprecated
<li> \refitem cmddontinclude \dontinclude
<li> \refitem cmddotfile \dotfile
<li> \refitem cmde \e
<li> \refitem cmdelse \else
<li> \refitem cmdelseif \elseif
<li> \refitem cmdem \em
<li> \refitem cmdendcode \endcode
<li> \refitem cmdendhtmlonly \endhtmlonly
<li> \refitem cmdendif \endif
<li> \refitem cmdendlatexonly \endlatexonly
<li> \refitem cmdendlink \endlink
<li> \refitem cmdendverbatim \endverbatim
<li> \refitem cmdenum \enum
<li> \refitem cmdexample \example
<li> \refitem cmdexception \exception
<li> \refitem cmdfdollar \f$
<li> \refitem cmdfbropen \f[
<li> \refitem cmdfbrclose \f]
<li> \refitem cmdfile \file
<li> \refitem cmdfn \fn
<li> \refitem cmdhideinitializer \hideinitializer
<li> \refitem cmdhtmlinclude \htmlinclude
<li> \refitem cmdhtmlonly \htmlonly
<li> \refitem cmdif \if
<li> \refitem cmdifnot \\ifnot
<li> \refitem cmdimage \image
<li> \refitem cmdinclude \include
<li> \refitem cmdingroup \ingroup
<li> \refitem cmdinternal \internal
<li> \refitem cmdinvariant \invariant
<li> \refitem cmdinterface \interface
<li> \refitem cmdlatexonly \latexonly
<li> \refitem cmdli \li
<li> \refitem cmdline \line
<li> \refitem cmdlink \link
<li> \refitem cmdmainpage \mainpage
<li> \refitem cmdname \name
<li> \refitem cmdnamespace \namespace
<li> \refitem cmdnosubgrouping \nosubgrouping
<li> \refitem cmdnote \note
<li> \refitem cmdoverload \overload
<li> \refitem cmdp \p
<li> \refitem cmdpackage \package
<li> \refitem cmdpage \page
<li> \refitem cmdpar \par
<li> \refitem cmdparam \param
<li> \refitem cmdpost \post
<li> \refitem cmdpre \pre
<li> \refitem cmdref \ref
<li> \refitem cmdrelates \relates
<li> \refitem cmdremarks \remarks
<li> \refitem cmdreturn \return
<li> \refitem cmdretval \retval
<li> \refitem cmdsa \sa
<li> \refitem cmdsection \section
<li> \refitem cmdshowinitializer \showinitializer
<li> \refitem cmdsince \since
<li> \refitem cmdskip \skip
<li> \refitem cmdskipline \skipline
<li> \refitem cmdstruct \struct
<li> \refitem cmdsubsection \subsection
<li> \refitem cmdtest \test
<li> \refitem cmdthrow \throw
<li> \refitem cmdtodo \todo
<li> \refitem cmdtypedef \typedef
<li> \refitem cmdunion \union
<li> \refitem cmduntil \until
<li> \refitem cmdvar \var
<li> \refitem cmdverbatim \verbatim
<li> \refitem cmdverbinclude \verbinclude
<li> \refitem cmdversion \version
<li> \refitem cmdwarning \warning
<li> \refitem cmdweakgroup \weakgroup
<li> \refitem cmddollar \$
<li> \refitem cmdat \@
<li> \refitem cmdbackslash \\
<li> \refitem cmdamp \&
<li> \refitem cmdlt \\<
<li> \refitem cmdgt \\>
<li> \refitem cmdhash \#
\htmlonly
</ul>
</multicol>
\endhtmlonly
\latexonly
\end{CompactList}
\end{multicols}
\endlatexonly

The following subsections provide a list of all commands that are recognized by
doxygen. Unrecognized commands are treated as normal text.

<h2>\htmlonly <center> --- \endhtmlonly 
    Structural indicators
    \htmlonly --- </center>\endhtmlonly</h2>

\subsection 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".

\subsection 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.
  
  \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>
\subsection 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>
\subsection 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>

\subsection 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>
\subsection 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>
\subsection 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

<hr>
\subsection 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 needed if a 
  comment block is \e not placed in front of 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 ommitted. 

  A full function declaration should be specified after the
  \\fn command. The argument ends at the end of the line.

  \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>
\subsection 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>
\subsection cmdingroup \ingroup (<groupname> [<groupname> <groupname>])

  \addindex \ingroup
  If the \\ingroup command is placed in a comment block of a
  class, file or namespace, then it will be added to the group or
  groups identified by \<groupname\>.

  \sa page \ref grouping "Grouping", sections \ref cmddefgroup "\\defgroup",
  \ref cmdaddtogroup "\\addtogroup" and \ref cmdweakgroup "\\weakgroup"

<hr>
\subsection cmdinterface \interface 

  \addindex \interface
  Indicates that a comment block contains documentation for an
  interface with name \<name\>. The arguments are equal to the \\class
  command.

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

<hr>
\subsection cmdinternal \internal
  
  \addindex \internal
  This command writes the message `For internal use only' to the output.
  All text after a \c \internal command is ignored.

<hr>
\subsection cmdmainpage \mainpage [(title)]

  \addindex \mainpage

  If the \\mainpage command is placed in a comment block the 
  block is used to customize the index page (in HTML) or
  the first chapter (in \f$\mbox{\LaTeX}\f$). 

  The title argument is optional and replaces the default title that
  doxygen normally generates.

  Here is an example:
\verbatim
/*! \mainpage My Personal Index Page
 *
 * \section intro Introduction
 *
 * This is the introduction.
 *
 * \section install Installation
 *
 * \subsection step1 Step 1: Opening the box
 *  
 * etc...
 */
\endverbatim

 You can refer to the main page using \\ref index.

 \sa section \ref cmdsection "\\section", 
     section \ref cmdsubsection "\\subsection" and 
     section \ref cmdpage "\\page".

<hr>
\subsection cmdname \name (header)  

This command turns a comment block into a header
definition of a member group. The
comment block should be followed by a 
<code>//@{ ... //@}</code> block containing the
members of the group.

See section \ref memgroup for an example.