doc/grouping.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page grouping Grouping
  18
  19 Doxygen has three mechanisms to group things together.
  20 One mechanism works at a global level, creating a new page
  21 for each group. These groups are called \ref modules "'modules'" in the documentation.
  22 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 Modules are a way to group things together on a separate page. You
  30 can document a group as a whole, as well as all individual members.
  31 Members of a group can be files, namespaces, classes, functions,
  32 variables, enums, typedefs, and defines, but also other groups.
  33
  34 To define a group, you should put the \ref cmddefgroup "\\defgroup"
  35 command in a special comment block. The first argument of the command
  36 is a label that should uniquely identify the group.
  37 The second argument is the name or title of the group as it should appear
  38 in the documentation.
  39
  40 You can make an entity a member of a specific group by putting
  41 a \ref cmdingroup "\\ingroup" command inside its documentation block.
  42
  43 To avoid putting \ref cmdingroup "\\ingroup" commands in the documentation
  44 for each member you can also group members together by the
  45 open marker <code>\@{</code> before the group and the
  46 closing marker <code>\@}</code> after the group. The markers can
  47 be put in the documentation of the group definition or in a separate
  48 documentation block.
  49
  50 Groups themselves can also be nested using these grouping markers.
  51
  52 You will get an error message when you use the same group label more than once.
  53 If you don't want doxygen to enforce unique labels, then you can
  54 use \ref cmdaddtogroup "\\addtogroup" instead of
  55 \ref cmddefgroup "\\defgroup".
  56 It can be used exactly like \ref cmddefgroup "\\defgroup",
  57 but when the group has been defined already, then it silently merges the
  58 existing documentation with the new one.
  59 The title of the group is optional for this command, so you can use
  60 \verbatim
  61 /** \addtogroup <label>
  62  *  @{
  63  */
  64 ...
  65
  66 /** @}*/
  67 \endverbatim
  68 to add additional members to a group that is defined in more detail elsewhere.
  69
  70 Note that compound entities (like classes, files and namespaces) can
  71 be put into multiple groups, but members (like variable, functions, typedefs
  72 and enums) can only be a member of one group
  73 (this restriction is in place to avoid ambiguous linking targets in case
  74 a member is not documented in the context of its class, namespace
  75 or file, but only visible as part of a group).
  76
  77 Doxygen will put members into the group whose definition has
  78 the highest "priority": e.g. An explicit \ref cmdingroup "\\ingroup" overrides
  79 an implicit grouping definition via <code>\@{</code> <code>\@}</code>.
  80 Conflicting grouping definitions with the same priority trigger a warning,
  81 unless one definition was for a member without any explicit documentation.
  82
  83 The following example puts VarInA into group A and silently resolves
  84 the conflict for IntegerVariable by putting it into group IntVariables,
  85 because the second instance of IntegerVariable
  86 is undocumented:
  87
  88 \verbatim
  89
  90 /**
  91  * \ingroup A
  92  */
  93 extern int VarInA;
  94
  95 /**
  96  * \defgroup IntVariables Global integer variables
  97  * @{
  98  */
  99
 100 /** an integer variable */
 101 extern int IntegerVariable;
 102
 103 /**@}*/
 104
 105 ....
 106
 107 /**
 108  * \defgroup Variables Global variables
 109  */
 110 /**@{*/
 111
 112 /** a variable in group A */
 113 int VarInA;
 114
 115 int IntegerVariable;
 116
 117 /**@}*/
 118 \endverbatim
 119
 120 The \ref cmdref "\\ref" command can be used to refer to a group.
 121 The first argument of the \\ref command should be group's label.
 122 To use a custom link name, you can put the name of the links in
 123 double quotes after the label, as shown by the following example
 124 \verbatim
 125 This is the \ref group_label "link" to this group.
 126 \endverbatim
 127
 128 The priorities of grouping definitions are (from highest to lowest):
 129 \ref cmdingroup "\\ingroup", \ref cmddefgroup "\\defgroup",
 130 \ref cmdaddtogroup "\\addtogroup", \ref cmdweakgroup "\\weakgroup".
 131 The \ref cmdweakgroup "\\weakgroup" command is exactly like \ref cmdaddtogroup "\\addtogroup"
 132 with a lower priority. It was added to allow "lazy" grouping
 133 definitions: you can use commands with a higher priority in your .h
 134 files to define the hierarchy and \ref cmdweakgroup "\\weakgroup"
 135 in .c files without having to duplicate the hierarchy exactly.
 136
 137 \par Example:
 138 \include group.cpp
 139
 140 \htmlonly
 141 </p>
 142 Click <a href="examples/group/html/modules.html">here</a>
 143 for the corresponding HTML documentation that is generated by doxygen.
 144 \endhtmlonly
 145 \latexonly
 146 See \hyperlink{modules_example}{Modules example}
 147 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
 148 \endlatexonly
 149
 150 \section memgroup Member Groups
 151
 152 If a compound (e.g. a class or file) has many members, it is often
 153 desired to group them together. Doxygen already automatically groups
 154 things together on type and protection level, but maybe you feel that
 155 this is not enough or that that default grouping is wrong.
 156 For instance, because you feel that members of different (syntactic)
 157 types belong to the same (semantic) group.
 158
 159 A member group is defined by
 160 a
 161 \verbatim
 162 ///@{
 163   ...
 164 ///@}
 165 \endverbatim
 166 block or a
 167 \verbatim
 168 /**@{*/
 169   ...
 170 /**@}*/
 171 \endverbatim
 172 block if you prefer C style
 173 comments. Note that the members of the group should be
 174 physically inside the member group's body.
 175
 176 Before the opening marker of a block a separate comment block may be
 177 placed. This block should contain the \ref cmdname "@@name"
 178 (or \ref cmdname "\\name") command and is used to specify the header
 179 of the group. Optionally, the comment block may also contain more
 180 detailed information about the group.
 181
 182 Nesting of member groups is not allowed.
 183
 184 If all members of a member group inside a class have the same type
 185 and protection level (for instance all are static public members),
 186 then the whole member group is displayed as a subgroup of
 187 the type/protection level group (the group is displayed as a
 188 subsection of the "Static Public Members" section for instance).
 189 If two or more members have different types, then the group is put
 190 at the same level as the automatically generated groups.
 191 If you want to force all member-groups of a class to be at the top level,
 192 you should put a \ref cmdnosubgrouping "\\nosubgrouping" command inside the
 193 documentation of the class.
 194
 195 \par Example:
 196 \include memgrp.cpp
 197
 198 \htmlonly
 199 </p>
 200 Click <a href="examples/memgrp/html/class_memgrp___test.html">here</a>
 201 for the corresponding HTML documentation that is generated by doxygen.
 202 \endhtmlonly
 203 \latexonly
 204 See \hyperlink{memgrp_example}{Member Groups example}
 205 for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
 206 \endlatexonly
 207
 208 Here Group1 is displayed as a subsection of the "Public Members". And
 209 Group2 is a separate section because it contains members with
 210 different protection levels (i.e. public and protected).
 211
 212 \section subpaging Subpaging
 213
 214 Information can be grouped into pages using the \ref cmdpage "\\page" and
 215 \ref cmdsubpage "\\mainpage" commands. Normally, this results in a
 216 flat list of pages, where the "main" page is the first in the list.
 217
 218 Instead of adding structure using the approach described in section
 219 \ref modules "modules" it is often more natural and convenient to add
 220 additional structure to the pages using the \ref cmdsubpage "\\subpage"
 221 command.
 222
 223 For a page A the \\subpage command adds a link to another page B and at
 224 the same time makes page B a subpage of A. This has the effect of making
 225 two groups GA and GB, where GB is part of GA, page A is put in group GA,
 226 and page B is put in group GB.
 227
 228 \htmlonly
 229 </p>
 230 Go to the <a href="formulas.html">next</a> section or return to the
 231  <a href="index.html">index</a>.
 232 <p>
 233 \endhtmlonly
 234
 235 */