|
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 grouping Grouping
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Doxygen has three mechanisms to group things together.
|
|
Packit |
1c1d7e |
One mechanism works at a global level, creating a new page
|
|
Packit |
1c1d7e |
for each group. These groups are called \ref modules "'modules'" in the documentation.
|
|
Packit |
1c1d7e |
The second mechanism works within a member list of some compound entity,
|
|
Packit |
1c1d7e |
and is referred to as a \ref memgroup "'member groups'".
|
|
Packit |
1c1d7e |
For \ref cmdpage "pages" there is a third grouping mechanism referred to
|
|
Packit |
1c1d7e |
as \ref subpaging "subpaging".
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section modules Modules
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Modules are a way to group things together on a separate page. You
|
|
Packit |
1c1d7e |
can document a group as a whole, as well as all individual members.
|
|
Packit |
1c1d7e |
Members of a group can be files, namespaces, classes, functions,
|
|
Packit |
1c1d7e |
variables, enums, typedefs, and defines, but also other groups.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To define a group, you should put the \ref cmddefgroup "\\defgroup"
|
|
Packit |
1c1d7e |
command in a special comment block. The first argument of the command
|
|
Packit |
1c1d7e |
is a label that should uniquely identify the group.
|
|
Packit |
1c1d7e |
The second argument is the name or title of the group as it should appear
|
|
Packit |
1c1d7e |
in the documentation.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
You can make an entity a member of a specific group by putting
|
|
Packit |
1c1d7e |
a \ref cmdingroup "\\ingroup" command inside its documentation block.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
To avoid putting \ref cmdingroup "\\ingroup" commands in the documentation
|
|
Packit |
1c1d7e |
for each member you can also group members together by the
|
|
Packit |
1c1d7e |
open marker \@{ before the group and the
|
|
Packit |
1c1d7e |
closing marker \@} after the group. The markers can
|
|
Packit |
1c1d7e |
be put in the documentation of the group definition or in a separate
|
|
Packit |
1c1d7e |
documentation block.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Groups themselves can also be nested using these grouping markers.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
You will get an error message when you use the same group label more than once.
|
|
Packit |
1c1d7e |
If you don't want doxygen to enforce unique labels, then you can
|
|
Packit |
1c1d7e |
use \ref cmdaddtogroup "\\addtogroup" instead of
|
|
Packit |
1c1d7e |
\ref cmddefgroup "\\defgroup".
|
|
Packit |
1c1d7e |
It can be used exactly like \ref cmddefgroup "\\defgroup",
|
|
Packit |
1c1d7e |
but when the group has been defined already, then it silently merges the
|
|
Packit |
1c1d7e |
existing documentation with the new one.
|
|
Packit |
1c1d7e |
The title of the group is optional for this command, so you can use
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/** \addtogroup <label>
|
|
Packit |
1c1d7e |
* @{
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
...
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/** @}*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
to add additional members to a group that is defined in more detail elsewhere.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Note that compound entities (like classes, files and namespaces) can
|
|
Packit |
1c1d7e |
be put into multiple groups, but members (like variable, functions, typedefs
|
|
Packit |
1c1d7e |
and enums) can only be a member of one group
|
|
Packit |
1c1d7e |
(this restriction is in place to avoid ambiguous linking targets in case
|
|
Packit |
1c1d7e |
a member is not documented in the context of its class, namespace
|
|
Packit |
1c1d7e |
or file, but only visible as part of a group).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Doxygen will put members into the group whose definition has
|
|
Packit |
1c1d7e |
the highest "priority": e.g. An explicit \ref cmdingroup "\\ingroup" overrides
|
|
Packit |
1c1d7e |
an implicit grouping definition via \@{ \@} .
|
|
Packit |
1c1d7e |
Conflicting grouping definitions with the same priority trigger a warning,
|
|
Packit |
1c1d7e |
unless one definition was for a member without any explicit documentation.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The following example puts VarInA into group A and silently resolves
|
|
Packit |
1c1d7e |
the conflict for IntegerVariable by putting it into group IntVariables,
|
|
Packit |
1c1d7e |
because the second instance of IntegerVariable
|
|
Packit |
1c1d7e |
is undocumented:
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/**
|
|
Packit |
1c1d7e |
* \ingroup A
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
extern int VarInA;
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/**
|
|
Packit |
1c1d7e |
* \defgroup IntVariables Global integer variables
|
|
Packit |
1c1d7e |
* @{
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/** an integer variable */
|
|
Packit |
1c1d7e |
extern int IntegerVariable;
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/**@}*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
....
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/**
|
|
Packit |
1c1d7e |
* \defgroup Variables Global variables
|
|
Packit |
1c1d7e |
*/
|
|
Packit |
1c1d7e |
/**@{*/
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/** a variable in group A */
|
|
Packit |
1c1d7e |
int VarInA;
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
int IntegerVariable;
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
/**@}*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The \ref cmdref "\\ref" command can be used to refer to a group.
|
|
Packit |
1c1d7e |
The first argument of the \\ref command should be group's label.
|
|
Packit |
1c1d7e |
To use a custom link name, you can put the name of the links in
|
|
Packit |
1c1d7e |
double quotes after the label, as shown by the following example
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
This is the \ref group_label "link" to this group.
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
The priorities of grouping definitions are (from highest to lowest):
|
|
Packit |
1c1d7e |
\ref cmdingroup "\\ingroup", \ref cmddefgroup "\\defgroup",
|
|
Packit |
1c1d7e |
\ref cmdaddtogroup "\\addtogroup", \ref cmdweakgroup "\\weakgroup".
|
|
Packit |
1c1d7e |
The \ref cmdweakgroup "\\weakgroup" command is exactly like \ref cmdaddtogroup "\\addtogroup"
|
|
Packit |
1c1d7e |
with a lower priority. It was added to allow "lazy" grouping
|
|
Packit |
1c1d7e |
definitions: you can use commands with a higher priority in your .h
|
|
Packit |
1c1d7e |
files to define the hierarchy and \ref cmdweakgroup "\\weakgroup"
|
|
Packit |
1c1d7e |
in .c files without having to duplicate the hierarchy exactly.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\par Example:
|
|
Packit |
1c1d7e |
\include group.cpp
|
|
Packit |
1c1d7e |
|
|
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{modules_example}{Modules example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section memgroup Member Groups
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If a compound (e.g. a class or file) has many members, it is often
|
|
Packit |
1c1d7e |
desired to group them together. Doxygen already automatically groups
|
|
Packit |
1c1d7e |
things together on type and protection level, but maybe you feel that
|
|
Packit |
1c1d7e |
this is not enough or that that default grouping is wrong.
|
|
Packit |
1c1d7e |
For instance, because you feel that members of different (syntactic)
|
|
Packit |
1c1d7e |
types belong to the same (semantic) group.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
A member group is defined by
|
|
Packit |
1c1d7e |
a
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
///@{
|
|
Packit |
1c1d7e |
...
|
|
Packit |
1c1d7e |
///@}
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
block or a
|
|
Packit |
1c1d7e |
\verbatim
|
|
Packit |
1c1d7e |
/**@{*/
|
|
Packit |
1c1d7e |
...
|
|
Packit |
1c1d7e |
/**@}*/
|
|
Packit |
1c1d7e |
\endverbatim
|
|
Packit |
1c1d7e |
block if you prefer C style
|
|
Packit |
1c1d7e |
comments. Note that the members of the group should be
|
|
Packit |
1c1d7e |
physically inside the member group's body.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Before the opening marker of a block a separate comment block may be
|
|
Packit |
1c1d7e |
placed. This block should contain the \ref cmdname "@@name"
|
|
Packit |
1c1d7e |
(or \ref cmdname "\\name") command and is used to specify the header
|
|
Packit |
1c1d7e |
of the group. Optionally, the comment block may also contain more
|
|
Packit |
1c1d7e |
detailed information about the group.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Nesting of member groups is not allowed.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
If all members of a member group inside a class have the same type
|
|
Packit |
1c1d7e |
and protection level (for instance all are static public members),
|
|
Packit |
1c1d7e |
then the whole member group is displayed as a subgroup of
|
|
Packit |
1c1d7e |
the type/protection level group (the group is displayed as a
|
|
Packit |
1c1d7e |
subsection of the "Static Public Members" section for instance).
|
|
Packit |
1c1d7e |
If two or more members have different types, then the group is put
|
|
Packit |
1c1d7e |
at the same level as the automatically generated groups.
|
|
Packit |
1c1d7e |
If you want to force all member-groups of a class to be at the top level,
|
|
Packit |
1c1d7e |
you should put a \ref cmdnosubgrouping "\\nosubgrouping" command inside the
|
|
Packit |
1c1d7e |
documentation of the class.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\par Example:
|
|
Packit |
1c1d7e |
\include memgrp.cpp
|
|
Packit |
1c1d7e |
|
|
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{memgrp_example}{Member Groups example}
|
|
Packit |
1c1d7e |
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
|
|
Packit |
1c1d7e |
\endlatexonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Here Group1 is displayed as a subsection of the "Public Members". And
|
|
Packit |
1c1d7e |
Group2 is a separate section because it contains members with
|
|
Packit |
1c1d7e |
different protection levels (i.e. public and protected).
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\section subpaging Subpaging
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Information can be grouped into pages using the \ref cmdpage "\\page" and
|
|
Packit |
1c1d7e |
\ref cmdsubpage "\\mainpage" commands. Normally, this results in a
|
|
Packit |
1c1d7e |
flat list of pages, where the "main" page is the first in the list.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Instead of adding structure using the approach described in section
|
|
Packit |
1c1d7e |
\ref modules "modules" it is often more natural and convenient to add
|
|
Packit |
1c1d7e |
additional structure to the pages using the \ref cmdsubpage "\\subpage"
|
|
Packit |
1c1d7e |
command.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
For a page A the \\subpage command adds a link to another page B and at
|
|
Packit |
1c1d7e |
the same time makes page B a subpage of A. This has the effect of making
|
|
Packit |
1c1d7e |
two groups GA and GB, where GB is part of GA, page A is put in group GA,
|
|
Packit |
1c1d7e |
and page B is put in group GB.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\htmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
Go to the next section or return to the
|
|
Packit |
1c1d7e |
index.
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
\endhtmlonly
|
|
Packit |
1c1d7e |
|
|
Packit |
1c1d7e |
*/
|