\hypertarget{grouping}{}\section{Grouping}\label{grouping}
 Doxygen has two mechanisms to group things together.  One mechanism works at a global level, creating a new page for each group. These groups are called \char`\"{}modules\char`\"{} in the documentation. The other mechanism works within a member list of some compound entity, and is refered to as a \char`\"{}member group\char`\"{}.

\hypertarget{modules}{}\subsection{Modules}\label{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 \hyperlink{cmddefgroup}{$\backslash$defgroup} command in a special comment block. The first argument of the command  is a label that should uniquely identify the group. You can make an  entity a member of a specific group by putting  a \hyperlink{cmdingroup}{$\backslash$ingroup} command inside its documentation block. The second argument is the title of the group.

To avoid putting \hyperlink{cmdingroup}{$\backslash$ingroup} commands in the documentation of each member you can also group members together by the  open marker {\tt @\{} before the group and the  closing marker {\tt @\}} after the group. The markers can  be put in the documentation of the group definition or in a separate  documentation block.

Groups 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 \hyperlink{cmdaddtogroup}{$\backslash$addtogroup} instead of \hyperlink{cmddefgroup}{$\backslash$defgroup}. It can be used exactly like \hyperlink{cmddefgroup}{$\backslash$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 

\footnotesize\begin{verbatim}
/** \addtogroup <label> */
/*\@{*/
/*\@}*/
\end{verbatim}\normalsize 
 to add 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 to avoid ambiguous linking targets).

Doxygen will put members into that group where the grouping definition had the highest priority: f.i. \hyperlink{cmdingroup}{$\backslash$ingroup} overrides any automatic grouping definition via {\tt @\{} {\tt @\}}. 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 Var\-In\-A into group A and silently resolves the conflict for Integer\-Variable by putting it into group Int\-Variables, because the second instance of Integer\-Variable is undocumented:



\footnotesize\begin{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;

/*@}*/
\end{verbatim}\normalsize 


The priorities of grouping definitions are (from highest to lowest): \hyperlink{cmdingroup}{$\backslash$ingroup}, \hyperlink{cmddefgroup}{$\backslash$defgroup}, \hyperlink{cmdaddtogroup}{$\backslash$addtogroup}, \hyperlink{cmdweakgroup}{$\backslash$weakgroup}. The last command is exactly like \hyperlink{cmdaddtogroup}{$\backslash$addtogroup} with a lower priority. It was added to allow \char`\"{}lazy\char`\"{} grouping definitions: you can use commands with a higher priority in your .h files to define the hierarchy and \hyperlink{cmdweakgroup}{$\backslash$weakgroup} in .c files without having to duplicate the hierarchy exactly.\begin{Desc}
\item[Example:]\par


\footnotesize\begin{verbatim}/** @defgroup group1 The First Group
 *  This is the first group
 *  @{
 */

/** @brief class C1 in group 1 */
class C1 {};

/** @brief class C2 in group 1 */
class C2 {};

/** function in group 1 */
void func() {}

/** @} */ // end of group1

/**
 *  @defgroup group2 The Second Group
 *  This is the second group
 */

/** @defgroup group3 The Third Group
 *  This is the third group
 */

/** @defgroup group4 The Fourth Group
 *  @ingroup group3
 *  Group 4 is a subgroup of group 3
 */

/**
 *  @ingroup group2
 *  @brief class C3 in group 2
 */
class C3 {};

/** @ingroup group2
 *  @brief class C4 in group 2
 */
class C4 {};

/** @ingroup group3
 *  @brief class C5 in @link group3 the third group@endlink.
 */
class C5 {};

/** @ingroup group1 group2 group3 group4
 *  namespace N1 is in four groups
 *  @sa @link group1 The first group@endlink, group2, group3, group4 
 *
 *  Also see @ref mypage2
 */
namespace N1 {};

/** @file
 *  @ingroup group3
 *  @brief this file in group 3
 */

/** @defgroup group5 The Fifth Group
 *  This is the fifth group
 *  @{
 */

/** @page mypage1 This is a section in group 5
 *  Text of the first section
 */

/** @page mypage2 This is another section in group 5
 *  Text of the second section
 */

/** @} */ // end of group5

/** @addtogroup group1
 *  
 *  More documentation for the first group.
 *  @{
 */

/** another function in group 1 */
void func2() {}

/** yet another function in group 1 */
void func3() {}

/** @} */ // end of group1


\end{verbatim}\normalsize 
\end{Desc}


\hypertarget{memgroup}{}\subsection{Member Groups}\label{memgroup}


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  

\footnotesize\begin{verbatim}
//@{ 
  ...
//@}
\end{verbatim}\normalsize 
  block or a  

\footnotesize\begin{verbatim}
/*@{*/ 
  ... 
/*@}*/ 
\end{verbatim}\normalsize 
  block if you prefer C style  comments. Note that the members of the group should be  physcially 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 \hyperlink{cmdname}{@name}  (or \hyperlink{cmdname}{$\backslash$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 \char`\"{}Static Public Members\char`\"{} 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 \hyperlink{cmdnosubgrouping}{$\backslash$nosubgrouping} command inside the documentation of the class.\begin{Desc}
\item[Example:]\par


\footnotesize\begin{verbatim}/** A class. Details */
class Test
{
  public:
    //@{
    /** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    //@}

    /** Function without group. Details. */
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};

void Test::func1InGroup1() {}
void Test::func2InGroup1() {}

/** @name Group2
 *  Description of group 2. 
 */
//@{
/** Function 2 in group 2. Details. */
void Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void Test::func1InGroup2() {}
//@}

/*! \file 
 *  docs for this file
 */

//@{
//! one description for all members of this group 
//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)
#define A 1
#define B 2
void glob_func();
//@}

\end{verbatim}\normalsize 
\end{Desc}


Here Group1 is displayed as a subsection of the \char`\"{}Public Members\char`\"{}. And Group2 is a separate section because it contains members with different protection levels (i.e. public and protected).



