|
Packit |
1c1d7e |
/******************************************************************************
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Copyright (C) 1997-2015 by Dimitri van Heesch.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Permission to use, copy, modify, and distribute this software and its
|
|
Packit |
1c1d7e |
* documentation under the terms of the GNU General Public License is hereby
|
|
Packit |
1c1d7e |
* granted. No representations are made about the suitability of this software
|
|
Packit |
1c1d7e |
* for any purpose. It is provided "as is" without express or implied warranty.
|
|
Packit |
1c1d7e |
* See the GNU General Public License for more details.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Documents produced by Doxygen are derivative works derived from the
|
|
Packit |
1c1d7e |
* input used in their production; they are not affected by this license.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
/*! \page docblocks Documenting the code
|
|
Packit |
1c1d7e |
\tableofcontents
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
This chapter covers two topics:
|
|
Packit |
1c1d7e |
1. How to put comments in your code such that doxygen incorporates them in
|
|
Packit |
1c1d7e |
the documentation it generates.
|
|
Packit |
1c1d7e |
This is further detailed in the \ref specialblock "next section".
|
|
Packit |
1c1d7e |
2. Ways to structure the contents of a comment block such that the output
|
|
Packit |
1c1d7e |
looks good, as explained in section \ref docstructure.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section specialblock Special comment blocks
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A special comment block is a C or C++ style comment block with some
|
|
Packit |
1c1d7e |
additional markings, so doxygen knows it is a piece of structured text that
|
|
Packit |
1c1d7e |
needs to end up in the generated documentation. The \ref cppblock "next" section
|
|
Packit |
1c1d7e |
presents the various styles supported by doxygen.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For Python, VHDL, Fortran, and Tcl code there are different commenting
|
|
Packit |
1c1d7e |
conventions, which can be found in sections \ref pythonblocks, \ref vhdlblocks,
|
|
Packit |
1c1d7e |
\ref fortranblocks, and \ref tclblocks respectively.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsection cppblock Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java)
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For each entity in the code there are two (or in some cases three) types of descriptions,
|
|
Packit |
1c1d7e |
which together form the documentation for that entity; a *brief* description and *detailed*
|
|
Packit |
1c1d7e |
description, both are optional. For methods and functions there is also a third
|
|
Packit |
1c1d7e |
type of description, the so called *in body* description, which consists of
|
|
Packit |
1c1d7e |
the concatenation of all comment blocks found within the body of the method or function.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Having more than one brief or detailed description is allowed (but not recommended,
|
|
Packit |
1c1d7e |
as the order in which the descriptions will appear is not specified).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
As the name suggest, a brief description is
|
|
Packit |
1c1d7e |
a short one-liner, whereas the detailed description provides longer,
|
|
Packit |
1c1d7e |
more detailed documentation. An "in body" description can also act as a detailed
|
|
Packit |
1c1d7e |
description or can describe a collection of implementation details.
|
|
Packit |
1c1d7e |
For the HTML output brief descriptions are also
|
|
Packit |
1c1d7e |
used to provide tooltips at places where an item is referenced.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
There are several ways to mark a comment block as a detailed description:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
You can use the JavaDoc style, which consist of a C-style comment
|
|
Packit |
1c1d7e |
block starting with two *'s, like this:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/**
|
|
Packit |
1c1d7e |
* ... text ...
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
or you can use the Qt style and add an exclamation mark (!)
|
|
Packit |
1c1d7e |
after the opening of a C-style comment block, as shown in this example:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
* ... text ...
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
In both cases the intermediate *'s are optional, so
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/*!
|
|
Packit |
1c1d7e |
... text ...
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
is also valid.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A third alternative is to use a block of at least two C++ comment
|
|
Packit |
1c1d7e |
lines, where each line starts with an additional slash or an
|
|
Packit |
1c1d7e |
exclamation mark. Here are examples of the two cases:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
///
|
|
Packit |
1c1d7e |
/// ... text ...
|
|
Packit |
1c1d7e |
///
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
or
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
//!
|
|
Packit |
1c1d7e |
//!... text ...
|
|
Packit |
1c1d7e |
//!
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Note that a blank line ends a documentation block in this case.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Some people like to make their comment blocks more visible in the
|
|
Packit |
1c1d7e |
documentation. For this purpose you can use the following:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/********************************************//**
|
|
Packit |
1c1d7e |
* ... text
|
|
Packit |
1c1d7e |
***********************************************/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
(note the 2 slashes to end the normal comment block and start a special comment block).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
or
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/////////////////////////////////////////////////
|
|
Packit |
1c1d7e |
/// ... text ...
|
|
Packit |
1c1d7e |
/////////////////////////////////////////////////
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For the brief description there are also several possibilities:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
One could use the \ref cmdbrief "\\brief" command with one of the
|
|
Packit |
1c1d7e |
above comment blocks. This command ends at the end of a paragraph,
|
|
Packit |
1c1d7e |
so the detailed description follows after an empty line.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is an example:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/*! \brief Brief description.
|
|
Packit |
1c1d7e |
* Brief description continued.
|
|
Packit |
1c1d7e |
*
|
|
Packit |
1c1d7e |
* Detailed description starts here.
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" is set to \c YES
|
|
Packit |
1c1d7e |
in the configuration file,
|
|
Packit |
1c1d7e |
then using JavaDoc style comment
|
|
Packit |
1c1d7e |
blocks will automatically start a brief description which ends at the
|
|
Packit |
1c1d7e |
first dot followed by a space or new line. Here is an example:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/** Brief description which ends at this dot. Details follow
|
|
Packit |
1c1d7e |
* here.
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
The option has the same effect for multi-line special C++ comments:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/// Brief description which ends at this dot. Details follow
|
|
Packit |
1c1d7e |
/// here.
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A third option is to use a special C++ style comment which does not
|
|
Packit |
1c1d7e |
span more than one line. Here are two examples:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/// Brief description.
|
|
Packit |
1c1d7e |
/** Detailed description. */
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
or
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
//! Brief description.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
//! Detailed description
|
|
Packit |
1c1d7e |
//! starts here.
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Note the blank line in the last example, which is required to separate the
|
|
Packit |
1c1d7e |
brief description from the block containing the detailed description. The
|
|
Packit |
1c1d7e |
\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" should also be set to \c NO
|
|
Packit |
1c1d7e |
for this case.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
As you can see doxygen is quite flexible. If you have multiple
|
|
Packit |
1c1d7e |
detailed descriptions, like in the following example:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
//! Brief description, which is
|
|
Packit |
1c1d7e |
//! really a detailed description since it spans multiple lines.
|
|
Packit |
1c1d7e |
/*! Another detailed description!
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
They will be joined. Note that this is also the case if the descriptions
|
|
Packit |
1c1d7e |
are at different places in the code! In this case the order will depend
|
|
Packit |
1c1d7e |
on the order in which doxygen parses the code.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Unlike most other documentation systems, doxygen also allows you to put
|
|
Packit |
1c1d7e |
the documentation of members (including global functions) in front of
|
|
Packit |
1c1d7e |
the \e definition. This way the documentation can be placed in the source
|
|
Packit |
1c1d7e |
file instead of the header file. This keeps the header file compact, and allows the
|
|
Packit |
1c1d7e |
implementer of the members more direct access to the documentation.
|
|
Packit |
1c1d7e |
As a compromise the brief description could be placed before the
|
|
Packit |
1c1d7e |
declaration and the detailed description before the member definition.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsubsection memberdoc Putting documentation after members
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If you want to document the members of a file, struct, union, class, or enum,
|
|
Packit |
1c1d7e |
it is sometimes desired to place the documentation block after the member
|
|
Packit |
1c1d7e |
instead of before. For this purpose you have to put an additional \< marker
|
|
Packit |
1c1d7e |
in the comment block. Note that this also works for the parameters
|
|
Packit |
1c1d7e |
of a function.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here are some examples:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int var; /*!< Detailed description after the member */
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
This block can be used to put a Qt style detailed
|
|
Packit |
1c1d7e |
documentation block \e after a member. Other ways to do the
|
|
Packit |
1c1d7e |
same are:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int var; /**< Detailed description after the member */
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
or
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int var; //!< Detailed description after the member
|
|
Packit |
1c1d7e |
//!<
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
or
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int var; ///< Detailed description after the member
|
|
Packit |
1c1d7e |
///<
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Most often one only wants to put a brief description after a member.
|
|
Packit |
1c1d7e |
This is done as follows:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int var; //!< Brief description after the member
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
or
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
int var; ///< Brief description after the member
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For functions one can use the \ref cmdparam "\@param" command to document the parameters
|
|
Packit |
1c1d7e |
and then use [in] , [out] , [in,out]
|
|
Packit |
1c1d7e |
to document the direction. For inline documentation this is also possible
|
|
Packit |
1c1d7e |
by starting with the direction attribute, e.g.
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
void foo(int v /**< [in] docs for input parameter v. */);
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Note that these blocks have the same structure and meaning as the
|
|
Packit |
1c1d7e |
special comment blocks in the previous section
|
|
Packit |
1c1d7e |
only the \< indicates that the member is
|
|
Packit |
1c1d7e |
located in front of the block instead of after the block.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is an example of the use of these comment blocks:
|
|
Packit |
1c1d7e |
\include afterdoc.h
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{afterdoc_example}{After Block example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\warning These blocks can only be used to document \e members and \e parameters.
|
|
Packit |
1c1d7e |
They cannot be used to document files, classes, unions, structs,
|
|
Packit |
1c1d7e |
groups, namespaces and enums themselves. Furthermore, the structural
|
|
Packit |
1c1d7e |
commands mentioned in the next section
|
|
Packit |
1c1d7e |
(like \\class ) are not allowed
|
|
Packit |
1c1d7e |
inside these comment blocks.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsubsection docexamples Examples
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is an example of a documented piece of C++ code using the Qt style:
|
|
Packit |
1c1d7e |
\include qtstyle.cpp
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{qtstyle_example}{QT Style example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The brief descriptions are included in the member overview of a
|
|
Packit |
1c1d7e |
class, namespace or file and are printed using a small italic font
|
|
Packit |
1c1d7e |
(this description can be hidden by setting
|
|
Packit |
1c1d7e |
\ref cfg_brief_member_desc "BRIEF_MEMBER_DESC" to \c NO in
|
|
Packit |
1c1d7e |
the config file). By default the brief descriptions become the first
|
|
Packit |
1c1d7e |
sentence of the detailed descriptions
|
|
Packit |
1c1d7e |
(but this can be changed by setting the \ref cfg_repeat_brief "REPEAT_BRIEF"
|
|
Packit |
1c1d7e |
tag to \c NO). Both the brief and the detailed descriptions are optional
|
|
Packit |
1c1d7e |
for the Qt style.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
By default a JavaDoc style documentation block behaves the same way as a
|
|
Packit |
1c1d7e |
Qt style documentation block. This is not according the JavaDoc specification
|
|
Packit |
1c1d7e |
however, where the first sentence of the documentation block is automatically
|
|
Packit |
1c1d7e |
treated as a brief description. To enable this behavior you should set
|
|
Packit |
1c1d7e |
\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to YES in the configuration
|
|
Packit |
1c1d7e |
file. If you enable this option and want to put a dot in the middle of a
|
|
Packit |
1c1d7e |
sentence without ending it, you should put a backslash and a space after it.
|
|
Packit |
1c1d7e |
Here is an example:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/** Brief description (e.g.\ using only a few words). Details follow. */
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is the same piece of code as shown above, this time documented using the
|
|
Packit |
1c1d7e |
JavaDoc style and \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" set to YES:
|
|
Packit |
1c1d7e |
\include jdstyle.cpp
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{jdstyle_example}{Javadoc Style example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Similarly, if one wishes the first sentence of a Qt style documentation
|
|
Packit |
1c1d7e |
block to automatically be treated as a brief description, one may set
|
|
Packit |
1c1d7e |
\ref cfg_qt_autobrief "QT_AUTOBRIEF" to YES in the configuration file.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsubsection structuralcommands Documentation at other places
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
In the examples in the previous section the comment blocks were always located *in
|
|
Packit |
1c1d7e |
front* of the declaration or definition of a file, class or namespace or *in
|
|
Packit |
1c1d7e |
front* or *after* one of its members.
|
|
Packit |
1c1d7e |
Although this is often comfortable, there may sometimes be reasons to put the
|
|
Packit |
1c1d7e |
documentation somewhere else. For documenting a file this is even
|
|
Packit |
1c1d7e |
required since there is no such thing as "in front of a file".
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Doxygen allows you to put your documentation blocks practically
|
|
Packit |
1c1d7e |
anywhere (the exception is inside the body of a function or inside a
|
|
Packit |
1c1d7e |
normal C style comment block).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The price you pay for not putting the
|
|
Packit |
1c1d7e |
documentation block directly before (or after) an item is the need to put a
|
|
Packit |
1c1d7e |
structural command inside the documentation block, which leads to some
|
|
Packit |
1c1d7e |
duplication of information. So in practice you should \e avoid the use of
|
|
Packit |
1c1d7e |
structural commands \e unless other requirements force you to do so.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Structural commands (like \ref cmd_intro "all other commands") start with a backslash
|
|
Packit |
1c1d7e |
(<tt>\\</tt>), or an at-sign (<tt>\@</tt>) if you prefer JavaDoc style,
|
|
Packit |
1c1d7e |
followed by a command name and one or more parameters.
|
|
Packit |
1c1d7e |
For instance, if you want to document the class \c Test in the example
|
|
Packit |
1c1d7e |
above, you could have also put the following documentation block somewhere
|
|
Packit |
1c1d7e |
in the input that is read by doxygen:
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/*! \class Test
|
|
Packit |
1c1d7e |
\brief A test class.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A more detailed class description.
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here the special command \c \\class is used to indicate that the
|
|
Packit |
1c1d7e |
comment block contains documentation for the class \c Test.
|
|
Packit |
1c1d7e |
Other structural commands are:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\c \\struct to document a C-struct.
|
|
Packit |
1c1d7e |
\c \\union to document a union.
|
|
Packit |
1c1d7e |
\c \\enum to document an enumeration type.
|
|
Packit |
1c1d7e |
\c \\fn to document a function.
|
|
Packit |
1c1d7e |
\c \\var to document a variable or typedef or enum value.
|
|
Packit |
1c1d7e |
\c \\def to document a \#define.
|
|
Packit |
1c1d7e |
\c \\typedef to document a type definition.
|
|
Packit |
1c1d7e |
\c \\file to document a file.
|
|
Packit |
1c1d7e |
\c \\namespace to document a namespace.
|
|
Packit |
1c1d7e |
\c \\package to document a Java package.
|
|
Packit |
1c1d7e |
\c \\interface to document an IDL interface.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
See section \ref commands for detailed information about these and many other
|
|
Packit |
1c1d7e |
commands.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To document a member of a C++ class, you must also document the class
|
|
Packit |
1c1d7e |
itself. The same holds for namespaces. To document a global C function,
|
|
Packit |
1c1d7e |
typedef, enum or preprocessor definition you must first document the file
|
|
Packit |
1c1d7e |
that contains it (usually this will be a header file, because that file
|
|
Packit |
1c1d7e |
contains the information that is exported to other source files).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
@attention Let's repeat that, because it is often overlooked:
|
|
Packit |
1c1d7e |
to document global objects (functions, typedefs, enum, macros, etc), you
|
|
Packit |
1c1d7e |
must document the file in which they are defined. In other words,
|
|
Packit |
1c1d7e |
there must at least be a \verbatim /*! \file */ \endverbatim
|
|
Packit |
1c1d7e |
or a \verbatim /** @file */ \endverbatim line in this file.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is an example of a C header named \c structcmd.h that is documented
|
|
Packit |
1c1d7e |
using structural commands:
|
|
Packit |
1c1d7e |
\include structcmd.h
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{structcmd_example}{Structural Commands example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Because each comment block in the example above contains a structural command, all
|
|
Packit |
1c1d7e |
the comment blocks could be moved to another location or input file
|
|
Packit |
1c1d7e |
(the source file for instance), without affecting the generated
|
|
Packit |
1c1d7e |
documentation. The disadvantage of this approach is that prototypes are
|
|
Packit |
1c1d7e |
duplicated, so all changes have to be made twice! Because of this you
|
|
Packit |
1c1d7e |
should first consider if this is really needed, and avoid structural
|
|
Packit |
1c1d7e |
commands if possible. I often receive examples that contain \\fn command
|
|
Packit |
1c1d7e |
in comment blocks which are place in front of a function. This is clearly
|
|
Packit |
1c1d7e |
a case where the \\fn command is redundant and will only lead to problems.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
When you place a comment block in a file with one of the following extensions
|
|
Packit |
1c1d7e |
`.dox`, `.txt`, or `.doc` then doxygen will hide this file from the file list.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If you have a file that doxygen cannot parse but still would like to document it,
|
|
Packit |
1c1d7e |
you can show it as-is using \ref cmdverbinclude "\\verbinclude", e.g.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/*! \file myscript.sh
|
|
Packit |
1c1d7e |
* Look at this nice script:
|
|
Packit |
1c1d7e |
* \verbinclude myscript.sh
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Make sure that the script is explicitly listed in the \ref cfg_input "INPUT" or
|
|
Packit |
1c1d7e |
that \ref cfg_file_patterns "FILE_PATTERNS" includes the `.sh` extension and the
|
|
Packit |
1c1d7e |
the script can be found in the path set via \ref cfg_example_path "EXAMPLE_PATH".
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsection pythonblocks Comment blocks in Python
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For Python there is a standard way of documenting the code using
|
|
Packit |
1c1d7e |
so called documentation strings. Such strings are stored in \c __doc__
|
|
Packit |
1c1d7e |
and can be retrieved at runtime. Doxygen will extract such comments
|
|
Packit |
1c1d7e |
and assume they have to be represented in a preformatted way.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\include docstring.py
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{python_example}{Python Docstring example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Note that in this case none of doxygen's \ref cmd_intro "special commands"
|
|
Packit |
1c1d7e |
are supported.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
There is also another way to document Python code using comments that
|
|
Packit |
1c1d7e |
start with "##". These type of comment blocks are more in line with the
|
|
Packit |
1c1d7e |
way documentation blocks work for the other languages supported by doxygen
|
|
Packit |
1c1d7e |
and this also allows the use of special commands.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is the same example again but now using doxygen style comments:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\include pyexample.py
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{py_example}{Python example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Since python looks more like Java than like C or C++, you should set
|
|
Packit |
1c1d7e |
\ref cfg_optimize_output_java "OPTIMIZE_OUTPUT_JAVA" to \c YES in the
|
|
Packit |
1c1d7e |
config file.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsection vhdlblocks Comment blocks in VHDL
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For VHDL a comment normally start with "--". Doxygen will extract comments
|
|
Packit |
1c1d7e |
starting with "--!". There are only two types of comment blocks in VHDL;
|
|
Packit |
1c1d7e |
a one line "--!" comment representing a brief description, and a multi-line
|
|
Packit |
1c1d7e |
"--!" comment (where the "--!" prefix is repeated for each line) representing
|
|
Packit |
1c1d7e |
a detailed description.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Comments are always located in front of the item that is being documented
|
|
Packit |
1c1d7e |
with one exception: for ports the comment can also be after the item
|
|
Packit |
1c1d7e |
and is then treated as a brief description for the port.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is an example VHDL file with doxygen comments:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\include mux.vhdl
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{vhdl_example}{VHDL example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To get proper looking output you need to set
|
|
Packit |
1c1d7e |
\ref cfg_optimize_output_vhdl "OPTIMIZE_OUTPUT_VHDL" to \c YES in the
|
|
Packit |
1c1d7e |
config file. This will also affect a number of other settings. When they
|
|
Packit |
1c1d7e |
were not already set correctly doxygen will produce a warning telling which
|
|
Packit |
1c1d7e |
settings where overruled.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsection fortranblocks Comment blocks in Fortran
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
When using doxygen for Fortran code you should
|
|
Packit |
1c1d7e |
set \ref cfg_optimize_for_fortran "OPTIMIZE_FOR_FORTRAN" to \c YES.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The parser tries to guess if the source code is fixed format Fortran or
|
|
Packit |
1c1d7e |
free format Fortran code. This may not always be correct. If not
|
|
Packit |
1c1d7e |
one should use \ref cfg_extension_mapping "EXTENSION_MAPPING" to correct this.
|
|
Packit |
1c1d7e |
By setting `EXTENSION_MAPPING = f=FortranFixed f90=FortranFree` files with
|
|
Packit |
1c1d7e |
extension \c f are interpreted as fixed format Fortran code and files with
|
|
Packit |
1c1d7e |
extension \c f90 are interpreted as free format Fortran code.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For Fortran "!>" or "!<" starts a comment and "!!" or "!>" can be used to
|
|
Packit |
1c1d7e |
continue an one line comment into a multi-line comment.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here is an example of a documented Fortran subroutine:
|
|
Packit |
1c1d7e |
\code{.f}
|
|
Packit |
1c1d7e |
!> Build the restriction matrix for the aggregation
|
|
Packit |
1c1d7e |
!! method.
|
|
Packit |
1c1d7e |
!! @param aggr information about the aggregates
|
|
Packit |
1c1d7e |
!! @todo Handle special case
|
|
Packit |
1c1d7e |
subroutine IntRestBuild(A,aggr,Restrict,A_ghost)
|
|
Packit |
1c1d7e |
implicit none
|
|
Packit |
1c1d7e |
Type(SpMtx), intent(in) :: A !< our fine level matrix
|
|
Packit |
1c1d7e |
Type(Aggrs), intent(in) :: aggr
|
|
Packit |
1c1d7e |
Type(SpMtx), intent(out) :: Restrict !< Our restriction matrix
|
|
Packit |
1c1d7e |
!...
|
|
Packit |
1c1d7e |
end subroutine
|
|
Packit |
1c1d7e |
\endcode
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
As an alternative you can also use comments in fixed format code:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\code{.f}
|
|
Packit |
1c1d7e |
C> Function comment
|
|
Packit |
1c1d7e |
C> another line of comment
|
|
Packit |
1c1d7e |
function A(i)
|
|
Packit |
1c1d7e |
C> input parameter
|
|
Packit |
1c1d7e |
integer i
|
|
Packit |
1c1d7e |
end function A
|
|
Packit |
1c1d7e |
\endcode
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\subsection tclblocks Comment blocks in Tcl
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Doxygen documentation can be included in normal Tcl comments.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To start a new documentation block start a line with \c ## (two hashes).
|
|
Packit |
1c1d7e |
All following comment lines and continuation lines will be added to this
|
|
Packit |
1c1d7e |
block. The block ends with a line not starting with a \c # (hash sign).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A brief documentation can be added with \c ;#< (semicolon, hash and
|
|
Packit |
1c1d7e |
lower then sign). The brief documentation also ends at a line not starting
|
|
Packit |
1c1d7e |
with a \c # (hash sign).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Inside doxygen comment blocks all normal doxygen markings are supported.
|
|
Packit |
1c1d7e |
The only exceptions are described in the following two paragraphs.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If a doxygen comment block ends with a line containing only
|
|
Packit |
1c1d7e |
\c #\\code or \c #\@code all code until a line only containing \c #\\endcode
|
|
Packit |
1c1d7e |
or \c #\@endcode is added to the generated documentation as code block.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If a doxygen comment block ends with a line containing only
|
|
Packit |
1c1d7e |
\c #\\verbatim or \c #\@verbatim all code until a line only containing
|
|
Packit |
1c1d7e |
\c #\\endverbatim or \c #\@endverbatim is added verbatim to the generated
|
|
Packit |
1c1d7e |
documentation.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To detect namespaces, classes, functions and variables the following
|
|
Packit |
1c1d7e |
Tcl commands are recognized. Documentation blocks can be put on the lines
|
|
Packit |
1c1d7e |
before the command.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
<tt>namespace eval ..</tt> Namespace
|
|
Packit |
1c1d7e |
<tt>proc ..</tt> Function
|
|
Packit |
1c1d7e |
<tt>variable ..</tt> Variable
|
|
Packit |
1c1d7e |
<tt>common ..</tt> Common variable
|
|
Packit |
1c1d7e |
<tt>itcl::class ..</tt> Class
|
|
Packit |
1c1d7e |
<tt>itcl::body ..</tt> Class method body definition
|
|
Packit |
1c1d7e |
<tt>oo::class create ..</tt> Class
|
|
Packit |
1c1d7e |
<tt>oo::define ..</tt> OO Class definition
|
|
Packit |
1c1d7e |
<tt>method ..</tt> Class method definitions
|
|
Packit |
1c1d7e |
<tt>constructor ..</tt> Class constructor
|
|
Packit |
1c1d7e |
<tt>destructor ..</tt> Class destructor
|
|
Packit |
1c1d7e |
<tt>public ..</tt> Set protection level
|
|
Packit |
1c1d7e |
<tt>protected ..</tt> Set protection level
|
|
Packit |
1c1d7e |
<tt>private ..</tt> Set protection level
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To use your own keywords you an map these keyword to the recognized commands
|
|
Packit |
1c1d7e |
using the \ref cfg_tcl_subs "TCL_SUBST" entry in the config file.
|
|
Packit |
1c1d7e |
The entry contain a list of word-keyword mappings. To use the itcl::*
|
|
Packit |
1c1d7e |
commands without the leading namespace use p.e.:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim TCL_SUBST = class itcl:class body itcl:body \endverbatim
|
|
Packit |
1c1d7e |
-->
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Following is an example using doxygen style comments:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\include tclexample.tcl
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Click here
|
|
Packit |
1c1d7e |
for the corresponding HTML documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
\latexonly
|
|
Packit |
1c1d7e |
See \hyperlink{tcl_example}{TCL example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section docstructure Anatomy of a comment block
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The previous section focused on how to make the comments in your code known
|
|
Packit |
1c1d7e |
to doxygen, it explained the difference between a brief and a detailed description, and
|
|
Packit |
1c1d7e |
the use of structural commands.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
In this section we look at the contents of the comment block itself.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Doxygen supports various styles of formatting your comments.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The simplest form is to use plain text. This will appear as-is in the output
|
|
Packit |
1c1d7e |
and is ideal for a short description.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For longer descriptions you often will find the
|
|
Packit |
1c1d7e |
need for some more structure, like a block of verbatim text, a list, or a
|
|
Packit |
1c1d7e |
simple table. For this doxygen supports the
|
|
Packit |
1c1d7e |
Markdown
|
|
Packit |
1c1d7e |
syntax, including parts of the
|
|
Packit |
1c1d7e |
Markdown Extra
|
|
Packit |
1c1d7e |
extension.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Markdown is designed to be very easy to read and write.
|
|
Packit |
1c1d7e |
It's formatting is inspired by plain text mail.
|
|
Packit |
1c1d7e |
Markdown works great for simple, generic formatting, like an introduction
|
|
Packit |
1c1d7e |
page for your project. Doxygen also supports reading of markdown files
|
|
Packit |
1c1d7e |
directly. For more details see chapter \ref markdown.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For programming language specific formatting doxygen has two
|
|
Packit |
1c1d7e |
forms of additional markup on top of Markdown formatting.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
1. Javadoc like markup.
|
|
Packit |
1c1d7e |
See \ref commands for a complete overview of all commands supported by doxygen.
|
|
Packit |
1c1d7e |
2. XML markup
|
|
Packit |
1c1d7e |
as specified in the C# standard. See \ref xmlcmds for the XML commands supported by doxygen.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If this is still not enough doxygen also supports a \ref htmlcmds "subset" of
|
|
Packit |
1c1d7e |
the HTML markup language.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
Go to the next section or return to the
|
|
Packit |
1c1d7e |
index.
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
*/
|