grouping.doc 7.96 KB
Newer Older
1 2 3 4
/******************************************************************************
 *
 * 
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
5
 * Copyright (C) 1997-2013 by Dimitri van Heesch.
6 7 8 9 10 11 12 13 14 15 16 17 18
 *
 * 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

19
Doxygen has three mechanisms to group things together. 
20
One mechanism works at a global level, creating a new page
21 22
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,
23
and is referred to as a \ref memgroup "'member groups'". 
24
For \ref cmdpage "pages" there is a third grouping mechanism referred to 
25
as \ref subpaging "subpaging".
26

27
\section modules Modules
28 29 30 31 32 33 34 35

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 
36 37 38 39 40
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 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
41 42 43
a \ref cmdingroup "\\ingroup" command inside its documentation block.

To avoid putting \ref cmdingroup "\\ingroup" commands in the documentation
44
for each member you can also group members together by the 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
45 46 47 48 49
open marker <code>\@{</code> before the group and the 
closing marker <code>\@}</code> after the group. The markers can 
be put in the documentation of the group definition or in a separate 
documentation block. 

50
Groups themselves can also be nested using these grouping markers.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
51

52
You will get an error message when you use the same group label more than once.
53 54 55 56 57 58
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.
59 60
The title of the group is optional for this command, so you can use
\verbatim
Dimitri van Heesch's avatar
Dimitri van Heesch committed
61 62 63 64 65 66
/** \addtogroup <label> 
 *  @{
 */
...

/** @}*/
67
\endverbatim
68
to add additional members to a group that is defined in more detail elsewhere.
69

Dimitri van Heesch's avatar
Dimitri van Heesch committed
70 71 72
Note that compound entities (like classes, files and namespaces) can
be put into multiple groups, but members (like variable, functions, typedefs
and enums) can only be a member of one group 
73 74 75 76 77 78 79 80 81 82 83 84 85
(this restriction is in place to avoid ambiguous linking targets in case 
a member is not documented in the context of its class, namespace
or file, but only visible as part of a group).

Doxygen will put members into the group whose definition has
the highest "priority": e.g. An explicit \ref cmdingroup "\\ingroup" overrides 
an implicit grouping definition via <code>\@{</code> <code>\@}</code>. 
Conflicting grouping definitions with the same priority trigger a warning, 
unless one definition was for a member without any explicit documentation. 

The following example puts VarInA into group A and silently resolves 
the conflict for IntegerVariable by putting it into group IntVariables, 
because the second instance of IntegerVariable
86 87 88 89 90 91 92 93 94 95 96
is undocumented:

\verbatim

/**
 * \ingroup A
 */
extern int VarInA;

/**
 * \defgroup IntVariables Global integer variables
Dimitri van Heesch's avatar
Dimitri van Heesch committed
97
 * @{
98 99 100 101 102
 */

/** an integer variable */
extern int IntegerVariable;

Dimitri van Heesch's avatar
Dimitri van Heesch committed
103
/**@}*/
104 105 106 107 108 109

....

/**
 * \defgroup Variables Global variables
 */
Dimitri van Heesch's avatar
Dimitri van Heesch committed
110
/**@{*/
111 112 113 114 115 116

/** a variable in group A */
int VarInA;

int IntegerVariable;

Dimitri van Heesch's avatar
Dimitri van Heesch committed
117
/**@}*/
118 119
\endverbatim

120 121 122 123 124 125 126 127
The \ref cmdref "\\ref" command can be used to refer to a group.
The first argument of the \\ref command should be group's label.
To use a custom link name, you can put the name of the links in 
double quotes after the label, as shown by the following example
\verbatim
This is the \ref group_label "link" to this group.
\endverbatim

128 129 130 131 132 133 134 135 136
The priorities of grouping definitions are (from highest to lowest):
\ref cmdingroup "\\ingroup", \ref cmddefgroup "\\defgroup",
\ref cmdaddtogroup "\\addtogroup", \ref cmdweakgroup "\\weakgroup".
The last command is exactly like \ref cmdaddtogroup "\\addtogroup"
with a lower priority. It was added to allow "lazy" grouping
definitions: you can use commands with a higher priority in your .h
files to define the hierarchy and \ref cmdweakgroup "\\weakgroup"
in .c files without having to duplicate the hierarchy exactly.

137 138 139 140 141 142 143 144
\par Example:
\verbinclude group.cpp

\htmlonly
Click <a href="$(DOXYGEN_DOCDIR)/examples/group/html/modules.html">here</a> 
for the corresponding HTML documentation that is generated by Doxygen.
\endhtmlonly

145
\section memgroup Member Groups
146 147 148 149 150 151 152 153 154 155 156

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
Dimitri van Heesch's avatar
Dimitri van Heesch committed
157
///@{ 
158
  ...
Dimitri van Heesch's avatar
Dimitri van Heesch committed
159
///@}
160 161 162
\endverbatim 
block or a 
\verbatim
Dimitri van Heesch's avatar
Dimitri van Heesch committed
163
/**@{*/ 
164
  ... 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
165
/**@}*/ 
166 167 168
\endverbatim 
block if you prefer C style 
comments. Note that the members of the group should be 
169
physically inside the member group's body.
170 171

Before the opening marker of a block a separate comment block may be 
172 173
placed. This block should contain the \ref cmdname "@@name" 
(or \ref cmdname "\\name") command and is used to specify the header 
174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
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:
\verbinclude memgrp.cpp

\htmlonly
Click <a href="$(DOXYGEN_DOCDIR)/examples/memgrp/html/class_test.html">here</a> 
for the corresponding HTML documentation that is generated by Doxygen.
\endhtmlonly

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).

202 203 204 205 206 207
\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. 

208 209
Instead of adding structure using the approach described in section
\ref modules "modules" it is often more natural and convenient to add 
210 211 212 213 214 215 216 217
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.

218 219 220 221 222
\htmlonly
Go to the <a href="formulas.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

223
*/