Release-1.8.0

1 files changed, 228 insertions, 0 deletions

diff --git a/trunk/doc/grouping.doc b/trunk/doc/grouping.doc
new file mode 100644
index 0000000..56f19f7
--- /dev/null
+++ b/trunk/doc/grouping.doc
@@ -0,0 +1,228 @@
+/******************************************************************************
+ *
+ * 
+ *
+ * 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
+
+*/