1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  * Copyright (C) 1997-2008 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 refered 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 \endverbatim

    65 to add additional members to a group that is defined in more detail elsewhere.

    66 

    67 Note that compound entities (like classes, files and namespaces) can

    68 be put into multiple groups, but members (like variable, functions, typedefs

    69 and enums) can only be a member of one group 

    70 (this restriction is in place to avoid ambiguous linking targets in case 

    71 a member is not documented in the context of its class, namespace

    72 or file, but only visible as part of a group).

    73 

    74 Doxygen will put members into the group whose definition has

    75 the highest "priority": e.g. An explicit \ref cmdingroup "\\ingroup" overrides 

    76 an implicit grouping definition via <code>\@{</code> <code>\@}</code>. 

    77 Conflicting grouping definitions with the same priority trigger a warning, 

    78 unless one definition was for a member without any explicit documentation. 

    79 

    80 The following example puts VarInA into group A and silently resolves 

    81 the conflict for IntegerVariable by putting it into group IntVariables, 

    82 because the second instance of IntegerVariable

    83 is undocumented:

    84 

    85 \verbatim

    86 

    87 /**

    88  * \ingroup A

    89  */

    90 extern int VarInA;

    91 

    92 /**

    93  * \defgroup IntVariables Global integer variables

    94  */

    95 /*@{*/

    96 

    97 /** an integer variable */

    98 extern int IntegerVariable;

    99 

   100 /*@}*/

   101 

   102 ....

   103 

   104 /**

   105  * \defgroup Variables Global variables

   106  */

   107 /*@{*/

   108 

   109 /** a variable in group A */

   110 int VarInA;

   111 

   112 int IntegerVariable;

   113 

   114 /*@}*/

   115 \endverbatim

   116 

   117 The \ref cmdref "\\ref" command can be used to refer to a group.

   118 The first argument of the \\ref command should be group's label.

   119 To use a custom link name, you can put the name of the links in 

   120 double quotes after the label, as shown by the following example

   121 \verbatim

   122 This is the \ref group_label "link" to this group.

   123 \endverbatim

   124 

   125 The priorities of grouping definitions are (from highest to lowest):

   126 \ref cmdingroup "\\ingroup", \ref cmddefgroup "\\defgroup",

   127 \ref cmdaddtogroup "\\addtogroup", \ref cmdweakgroup "\\weakgroup".

   128 The last command is exactly like \ref cmdaddtogroup "\\addtogroup"

   129 with a lower priority. It was added to allow "lazy" grouping

   130 definitions: you can use commands with a higher priority in your .h

   131 files to define the hierarchy and \ref cmdweakgroup "\\weakgroup"

   132 in .c files without having to duplicate the hierarchy exactly.

   133 

   134 \par Example:

   135 \verbinclude group.cpp

   136 

   137 \htmlonly

   138 Click <a href="$(DOXYGEN_DOCDIR)/examples/group/html/modules.html">here</a> 

   139 for the corresponding HTML documentation that is generated by Doxygen.

   140 \endhtmlonly

   141 

   142 \section memgroup Member Groups

   143 

   144 If a compound (e.g. a class or file) has many members, it is often 

   145 desired to group them together. Doxygen already automatically groups 

   146 things together on type and protection level, but maybe you feel that 

   147 this is not enough or that that default grouping is wrong. 

   148 For instance, because you feel that members of different (syntactic) 

   149 types belong to the same (semantic) group.

   150 

   151 A member group is defined by 

   152 a 

   153 \verbatim

   154 //@{ 

   155   ...

   156 //@}

   157 \endverbatim 

   158 block or a 

   159 \verbatim

   160 /*@{*/ 

   161   ... 

   162 /*@}*/ 

   163 \endverbatim 

   164 block if you prefer C style 

   165 comments. Note that the members of the group should be 

   166 physcially inside the member group's body.

   167 

   168 Before the opening marker of a block a separate comment block may be 

   169 placed. This block should contain the \ref cmdname "@@name" 

   170 (or \ref cmdname "\\name") command and is used to specify the header 

   171 of the group. Optionally, the comment block may also contain more

   172 detailed information about the group.

   173 

   174 Nesting of member groups is not allowed. 

   175 

   176 If all members of a member group inside a class have the same type 

   177 and protection level (for instance all are static public members), 

   178 then the whole member group is displayed as a subgroup of 

   179 the type/protection level group (the group is displayed as a 

   180 subsection of the "Static Public Members" section for instance). 

   181 If two or more members have different types, then the group is put 

   182 at the same level as the automatically generated groups.

   183 If you want to force all member-groups of a class to be at the top level, 

   184 you should put a \ref cmdnosubgrouping "\\nosubgrouping" command inside the

   185 documentation of the class. 

   186 

   187 \par Example:

   188 \verbinclude memgrp.cpp

   189 

   190 \htmlonly

   191 Click <a href="$(DOXYGEN_DOCDIR)/examples/memgrp/html/class_test.html">here</a> 

   192 for the corresponding HTML documentation that is generated by Doxygen.

   193 \endhtmlonly

   194 

   195 Here Group1 is displayed as a subsection of the "Public Members". And

   196 Group2 is a separate section because it contains members with

   197 different protection levels (i.e. public and protected).

   198 

   199 \htmlonly

   200 Go to the <a href="formulas.html">next</a> section or return to the

   201  <a href="index.html">index</a>.

   202 \endhtmlonly

   203 

   204 \section subpaging Subpaging

   205 

   206 Information can be grouped into pages using the \ref cmdpage "\\page" and

   207 \ref cmdsubpage "\\mainpage" commands. Normally, this results in a

   208 flat list of pages, where the "main" page is the first in the list. 

   209 

   210 Instead of adding structure using the approach decribed in section

   211 \ref modules "modules" it is often more natural and convienent to add 

   212 additional structure to the pages using the \ref cmdsubpage "\\subpage" 

   213 command. 

   214 

   215 For a page A the \\subpage command adds a link to another page B and at 

   216 the same time makes page B a subpage of A. This has the effect of making

   217 two groups GA and GB, where GB is part of GA, page A is put in group GA, 

   218 and page B is put in group GB.

   219 

   220 \htmlonly

   221 Go to the <a href="formulas.html">next</a> section or return to the

   222  <a href="index.html">index</a>.

   223 \endhtmlonly

   224 

   225 */