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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Grouping</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('grouping.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Grouping </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>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 <a class="el" href="grouping.html#modules">'modules'</a> in the documentation. The second mechanism works within a member list of some compound entity, and is referred to as a <a class="el" href="grouping.html#memgroup">'member groups'</a>. For <a class="el" href="commands.html#cmdpage">pages</a> there is a third grouping mechanism referred to as <a class="el" href="grouping.html#subpaging">subpaging</a>.</p>
<h1><a class="anchor" id="modules"></a>
Modules</h1>
<p>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.</p>
<p>To define a group, you should put the <a class="el" href="commands.html#cmddefgroup">\defgroup</a> 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.</p>
<p>You can make an entity a member of a specific group by putting a <a class="el" href="commands.html#cmdingroup">\ingroup</a> command inside its documentation block.</p>
<p>To avoid putting <a class="el" href="commands.html#cmdingroup">\ingroup</a> commands in the documentation for 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.</p>
<p>Groups themselves can also be nested using these grouping markers.</p>
<p>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 <a class="el" href="commands.html#cmdaddtogroup">\addtogroup</a> instead of <a class="el" href="commands.html#cmddefgroup">\defgroup</a>. It can be used exactly like <a class="el" href="commands.html#cmddefgroup">\defgroup</a>, 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 </p><pre class="fragment">/** \addtogroup <label>
* @{
*/
...
/** @}*/
</pre><p> to add additional members to a group that is defined in more detail elsewhere.</p>
<p>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 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).</p>
<p>Doxygen will put members into the group whose definition has the highest "priority": e.g. An explicit <a class="el" href="commands.html#cmdingroup">\ingroup</a> 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.</p>
<p>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 is undocumented:</p>
<pre class="fragment">/**
* \ingroup A
*/
extern int VarInA;
/**
* \defgroup IntVariables Global integer variables
* @{
*/
/** an integer variable */
extern int IntegerVariable;
/**@}*/
....
/**
* \defgroup Variables Global variables
*/
/**@{*/
/** a variable in group A */
int VarInA;
int IntegerVariable;
/**@}*/
</pre><p>The <a class="el" href="commands.html#cmdref">\ref</a> 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 </p><pre class="fragment">This is the \ref group_label "link" to this group.
</pre><p>The priorities of grouping definitions are (from highest to lowest): <a class="el" href="commands.html#cmdingroup">\ingroup</a>, <a class="el" href="commands.html#cmddefgroup">\defgroup</a>, <a class="el" href="commands.html#cmdaddtogroup">\addtogroup</a>, <a class="el" href="commands.html#cmdweakgroup">\weakgroup</a>. The last command is exactly like <a class="el" href="commands.html#cmdaddtogroup">\addtogroup</a> 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 <a class="el" href="commands.html#cmdweakgroup">\weakgroup</a> in .c files without having to duplicate the hierarchy exactly.</p>
<dl class="section user"><dt>Example:</dt><dd><div class="fragment"><div class="line"><span class="comment">/** @defgroup group1 The First Group</span></div><div class="line"><span class="comment"> * This is the first group</span></div><div class="line"><span class="comment"> * @{</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @brief class C1 in group 1 */</span></div><div class="line"><span class="keyword">class </span>C1 {};</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @brief class C2 in group 1 */</span></div><div class="line"><span class="keyword">class </span>C2 {};</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** function in group 1 */</span></div><div class="line"><span class="keywordtype">void</span> func() {}</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @} */</span> <span class="comment">// end of group1</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/**</span></div><div class="line"><span class="comment"> * @defgroup group2 The Second Group</span></div><div class="line"><span class="comment"> * This is the second group</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @defgroup group3 The Third Group</span></div><div class="line"><span class="comment"> * This is the third group</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @defgroup group4 The Fourth Group</span></div><div class="line"><span class="comment"> * @ingroup group3</span></div><div class="line"><span class="comment"> * Group 4 is a subgroup of group 3</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/**</span></div><div class="line"><span class="comment"> * @ingroup group2</span></div><div class="line"><span class="comment"> * @brief class C3 in group 2</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="keyword">class </span>C3 {};</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @ingroup group2</span></div><div class="line"><span class="comment"> * @brief class C4 in group 2</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="keyword">class </span>C4 {};</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @ingroup group3</span></div><div class="line"><span class="comment"> * @brief class C5 in @link group3 the third group@endlink.</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="keyword">class </span>C5 {};</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @ingroup group1 group2 group3 group4</span></div><div class="line"><span class="comment"> * namespace N1 is in four groups</span></div><div class="line"><span class="comment"> * @sa @link group1 The first group@endlink, group2, group3, group4 </span></div><div class="line"><span class="comment"> *</span></div><div class="line"><span class="comment"> * Also see @ref mypage2</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="keyword">namespace </span>N1 {};</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @file</span></div><div class="line"><span class="comment"> * @ingroup group3</span></div><div class="line"><span class="comment"> * @brief this file in group 3</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @defgroup group5 The Fifth Group</span></div><div class="line"><span class="comment"> * This is the fifth group</span></div><div class="line"><span class="comment"> * @{</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @page mypage1 This is a section in group 5</span></div><div class="line"><span class="comment"> * Text of the first section</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @page mypage2 This is another section in group 5</span></div><div class="line"><span class="comment"> * Text of the second section</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @} */</span> <span class="comment">// end of group5</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @addtogroup group1</span></div><div class="line"><span class="comment"> * </span></div><div class="line"><span class="comment"> * More documentation for the first group.</span></div><div class="line"><span class="comment"> * @{</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** another function in group 1 */</span></div><div class="line"><span class="keywordtype">void</span> func2() {}</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** yet another function in group 1 */</span></div><div class="line"><span class="keywordtype">void</span> func3() {}</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @} */</span> <span class="comment">// end of group1</span></div><div class="line"></div></div><!-- fragment --></dd></dl>
<p>
</p>
Click <a href="examples/group/html/modules.html">here</a>
for the corresponding HTML documentation that is generated by doxygen.
<h1><a class="anchor" id="memgroup"></a>
Member Groups</h1>
<p>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.</p>
<p>A member group is defined by a </p><pre class="fragment">///@{
...
///@}
</pre><p> block or a </p><pre class="fragment">/**@{*/
...
/**@}*/
</pre><p> block if you prefer C style comments. Note that the members of the group should be physically inside the member group's body.</p>
<p>Before the opening marker of a block a separate comment block may be placed. This block should contain the <a class="el" href="commands.html#cmdname">@name</a> (or <a class="el" href="commands.html#cmdname">\name</a>) command and is used to specify the header of the group. Optionally, the comment block may also contain more detailed information about the group.</p>
<p>Nesting of member groups is not allowed.</p>
<p>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 <a class="el" href="commands.html#cmdnosubgrouping">\nosubgrouping</a> command inside the documentation of the class.</p>
<dl class="section user"><dt>Example:</dt><dd><div class="fragment"><div class="line"><span class="comment">/** A class. Details */</span></div><div class="line"><span class="keyword">class </span>Memgrp_Test</div><div class="line">{</div><div class="line"> <span class="keyword">public</span>:<span class="comment"></span></div><div class="line"><span class="comment"> //@{</span></div><div class="line"><span class="comment"></span><span class="comment"> /** Same documentation for both members. Details */</span></div><div class="line"> <span class="keywordtype">void</span> func1InGroup1();</div><div class="line"> <span class="keywordtype">void</span> func2InGroup1();<span class="comment"></span></div><div class="line"><span class="comment"> //@}</span></div><div class="line"><span class="comment"></span><span class="comment"></span></div><div class="line"><span class="comment"> /** Function without group. Details. */</span></div><div class="line"> <span class="keywordtype">void</span> ungroupedFunction();</div><div class="line"> <span class="keywordtype">void</span> func1InGroup2();</div><div class="line"> <span class="keyword">protected</span>:</div><div class="line"> <span class="keywordtype">void</span> func2InGroup2();</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">void</span> Memgrp_Test::func1InGroup1() {}</div><div class="line"><span class="keywordtype">void</span> Memgrp_Test::func2InGroup1() {}</div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">/** @name Group2</span></div><div class="line"><span class="comment"> * Description of group 2. </span></div><div class="line"><span class="comment"> */</span><span class="comment"></span></div><div class="line"><span class="comment">///@{</span></div><div class="line"><span class="comment"></span><span class="comment">/** Function 2 in group 2. Details. */</span></div><div class="line"><span class="keywordtype">void</span> Memgrp_Test::func2InGroup2() {}<span class="comment"></span></div><div class="line"><span class="comment">/** Function 1 in group 2. Details. */</span></div><div class="line"><span class="keywordtype">void</span> Memgrp_Test::func1InGroup2() {}<span class="comment"></span></div><div class="line"><span class="comment">///@}</span></div><div class="line"><span class="comment"></span><span class="comment"></span></div><div class="line"><span class="comment">/*! \file </span></div><div class="line"><span class="comment"> * docs for this file</span></div><div class="line"><span class="comment"> */</span></div><div class="line"><span class="comment"></span></div><div class="line"><span class="comment">//!@{</span></div><div class="line"><span class="comment">//! one description for all members of this group </span></div><div class="line"><span class="comment">//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)</span></div><div class="line"><span class="comment"></span><span class="preprocessor">#define A 1</span></div><div class="line"><span class="preprocessor">#define B 2</span></div><div class="line"><span class="keywordtype">void</span> glob_func();<span class="comment"></span></div><div class="line"><span class="comment">//!@}</span></div></div><!-- fragment --></dd></dl>
<p>
</p>
Click <a href="examples/memgrp/html/class_test.html">here</a>
for the corresponding HTML documentation that is generated by doxygen.
<p>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).</p>
<h1><a class="anchor" id="subpaging"></a>
Subpaging</h1>
<p>Information can be grouped into pages using the <a class="el" href="commands.html#cmdpage">\page</a> and <a class="el" href="commands.html#cmdsubpage">\mainpage</a> commands. Normally, this results in a flat list of pages, where the "main" page is the first in the list.</p>
<p>Instead of adding structure using the approach described in section <a class="el" href="grouping.html#modules">modules</a> it is often more natural and convenient to add additional structure to the pages using the <a class="el" href="commands.html#cmdsubpage">\subpage</a> command.</p>
<p>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.</p>
<p>
</p>
Go to the <a href="formulas.html">next</a> section or return to the
<a href="index.html">index</a>.
<p>
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
