doxygen--03--分组grouping

 oxygen分组的两种机制：

第一种是全局地为每一个组创建一个网页，此时分组被称为"module"。
第二种是用于复合实体中的成员列表，此时分组被称为"member group"。Module是一种把内容在单个网页上分组的方法。分组可以包括files，namespace，classes，functions，variables，enums，typedefs和defines，也可以包含其它分组。复合实体（compound entities）如类、文件、命名空间等可以分布在多个分组中，而成员实体（member）如变量、函数、typedef等只能归属于一个分组。

定义分组的方法是在特殊注释块中使用命令\defgroup和\addtogroup。 defgroup的格式如下：

\defgroup <唯一标识名> （中间可以有空格的标题 ）

两次使用同一标识名，在doxygen解析的时候会出现错误。命令addtogroup与defgroup不同的地方在于，如果使用了同一标识，则会在改组中加入新的项，如果标识不重复，则会创建分组。addtogroup中的标题是可选的。

声明分组之后，如果要使某个实体归属某一分组，需要使用ingroup命令。避免在每个成员之前都使用ingroup命令，可以将member用open marker‘@{’和close marker‘@}’封装起来。

doxygen将会把members放进高优先级的分组中，比如一个显示的\ingroup会覆盖一个隐式的通过@{@}定义的group。相同优先级分组的冲突会引发一个警告，除非这个定义没有显式的注释。

下面的例子把VarInA放到group A中，silently resolves IntegerVariable 放进group IntVariables，因为第二个IntegerVariable 是没有注释的（不然也会有一个警告）。

/**
* \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;

/*@}*/


上面这些命令都是有优先级的，doxygen会根据优先级将实体放入具有最高优先级的分组之中。它们的优先级顺序是：ingroup，defgroup，addtogroup，weakgroup。weakgroup类似一个低优先级的addtogroup。在.h文件中可以使用高优先级的命令定义层次结构，在.c文件中\weakgroup就不需要准确遵循.h文件中定义的层次结构。

如果要把不同的类型归入同一分组内，就要使用Member group，它的定义方法如下：

//@{
...
//@}

或者

/*@{*/
...
/*@}*/
     

Member group不可以嵌套。