summaryrefslogtreecommitdiffstats
path: root/doc/grouping.doc
blob: 71a8e375ccd2c594fa37e75f8f728d523245e6a3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
/******************************************************************************
 *
 * 
 *
 * 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 grouping Grouping

Doxygen has two mechanisms to group things together. 
One mechanism works at a global level, creating a new page
for each group. These groups are called "modules" in the documentation.
The other mechanism works within a member list of some compound entity,
and is refered to as a "member group".

\subsection 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.  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
of each member you can also group members together by the 
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. 

Groups can also be nested using these grouping markers.

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 
(this restriction is to avoid ambiguous linking targets).

\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

\subsection 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 
physcially 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:
\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).

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

*/