/******************************************************************************
*
*
*
* Copyright (C) 1997-2015 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 grouping Grouping
Doxygen has three mechanisms to group things together.
One mechanism works at a global level, creating a new page
for each group. These groups are called \ref modules "'modules'" in the documentation.
The second mechanism works within a member list of some compound entity,
and is referred to as a \ref memgroup "'member groups'".
For \ref cmdpage "pages" there is a third grouping mechanism referred to
as \ref subpaging "subpaging".
\section modules Modules
Modules are a way to group things together on a separate page. You
can document a group as a whole, as well as all individual members.
Members of a group can be files, namespaces, classes, functions,
variables, enums, typedefs, and defines, but also other groups.
To define a group, you should put the \ref cmddefgroup "\\defgroup"
command in a special comment block. The first argument of the command
is a label that should uniquely identify the group.
The second argument is the name or title of the group as it should appear
in the documentation.
You can make an entity a member of a specific group by putting
a \ref cmdingroup "\\ingroup" command inside its documentation block.
To avoid putting \ref cmdingroup "\\ingroup" commands in the documentation
for each member you can also group members together by the
open marker \@{ before the group and the
closing marker \@} after the group. The markers can
be put in the documentation of the group definition or in a separate
documentation block.
Groups themselves can also be nested using these grouping markers.
You will get an error message when you use the same group label more than once.
If you don't want doxygen to enforce unique labels, then you can
use \ref cmdaddtogroup "\\addtogroup" instead of
\ref cmddefgroup "\\defgroup".
It can be used exactly like \ref cmddefgroup "\\defgroup",
but when the group has been defined already, then it silently merges the
existing documentation with the new one.
The title of the group is optional for this command, so you can use
\verbatim
/** \addtogroup
Click here
for the corresponding HTML documentation that is generated by Doxygen.
\endhtmlonly
\latexonly
See \hyperlink{modules_example}{Modules example}
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
\endlatexonly
\section memgroup Member Groups
If a compound (e.g. a class or file) has many members, it is often
desired to group them together. Doxygen already automatically groups
things together on type and protection level, but maybe you feel that
this is not enough or that that default grouping is wrong.
For instance, because you feel that members of different (syntactic)
types belong to the same (semantic) group.
A member group is defined by
a
\verbatim
///@{
...
///@}
\endverbatim
block or a
\verbatim
/**@{*/
...
/**@}*/
\endverbatim
block if you prefer C style
comments. Note that the members of the group should be
physically inside the member group's body.
Before the opening marker of a block a separate comment block may be
placed. This block should contain the \ref cmdname "@@name"
(or \ref cmdname "\\name") command and is used to specify the header
of the group. Optionally, the comment block may also contain more
detailed information about the group.
Nesting of member groups is not allowed.
If all members of a member group inside a class have the same type
and protection level (for instance all are static public members),
then the whole member group is displayed as a subgroup of
the type/protection level group (the group is displayed as a
subsection of the "Static Public Members" section for instance).
If two or more members have different types, then the group is put
at the same level as the automatically generated groups.
If you want to force all member-groups of a class to be at the top level,
you should put a \ref cmdnosubgrouping "\\nosubgrouping" command inside the
documentation of the class.
\par Example:
\include memgrp.cpp
\htmlonly
Click here
for the corresponding HTML documentation that is generated by Doxygen.
\endhtmlonly
\latexonly
See \hyperlink{memgrp_example}{Member Groups example}
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
\endlatexonly
Here Group1 is displayed as a subsection of the "Public Members". And
Group2 is a separate section because it contains members with
different protection levels (i.e. public and protected).
\section subpaging Subpaging
Information can be grouped into pages using the \ref cmdpage "\\page" and
\ref cmdsubpage "\\mainpage" commands. Normally, this results in a
flat list of pages, where the "main" page is the first in the list.
Instead of adding structure using the approach described in section
\ref modules "modules" it is often more natural and convenient to add
additional structure to the pages using the \ref cmdsubpage "\\subpage"
command.
For a page A the \\subpage command adds a link to another page B and at
the same time makes page B a subpage of A. This has the effect of making
two groups GA and GB, where GB is part of GA, page A is put in group GA,
and page B is put in group GB.
\htmlonly
Go to the next section or return to the
index.