diff options
Diffstat (limited to 'trunk/doc/grouping.doc')
| -rw-r--r-- | trunk/doc/grouping.doc | 228 |
1 files changed, 0 insertions, 228 deletions
diff --git a/trunk/doc/grouping.doc b/trunk/doc/grouping.doc deleted file mode 100644 index 56f19f7..0000000 --- a/trunk/doc/grouping.doc +++ /dev/null @@ -1,228 +0,0 @@ -/****************************************************************************** - * - * - * - * Copyright (C) 1997-2012 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 three mechanisms to group things together. -One mechanism works at a global level, creating a new page -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, -and is referred to as a \ref memgroup "'member groups'". -For \ref cmdpage "pages" there is a third grouping mechanism referred to -as \ref subpaging "subpaging". - -\section 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. -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 -a \ref cmdingroup "\\ingroup" command inside its documentation block. - -To avoid putting \ref cmdingroup "\\ingroup" 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. - -Groups themselves can also be nested using these grouping markers. - -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 \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. -The title of the group is optional for this command, so you can use -\verbatim -/** \addtogroup <label> - * @{ - */ -... - -/** @}*/ -\endverbatim -to add additional members to a group that is defined in more detail elsewhere. - -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). - -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 -is undocumented: - -\verbatim - -/** - * \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; - -/**@}*/ -\endverbatim - -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 - -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. - -\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 - -\section 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 -physically 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 - -\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. - -Instead of adding structure using the approach described in section -\ref modules "modules" it is often more natural and convenient to add -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. - -\htmlonly -Go to the <a href="formulas.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ |