DoxyGen文档介绍
DoxyGen文档介绍
第四章：Grouping归组
Doxygen有两种机制进行归组。第一种是全局级，为每个group创建一个新的page。这些groups在注释中被称作“modules”。另一种机制使用于一些compound entity中的member list，称为“member group”。
Modules模块
Modules是一种归组things在分离的page上的方式。组的成员可以是file，namespace，classes，functions，variables，enums，typedefs和defines，但也可以是其他groups。
要定义一个group，应该在一个特殊注释块放置/defgroup。命令的第一个参数应该是唯一标志该group的标签。要将一个entity归为某个group的一个member，在entity前放置/ingroup命令。第二个参数是group的title。
要避免在注释中每个member前放置/ingroup命令，可以将member用@{和@}封装起来。@{@}标记可以放置group的注释中，也可以在一个独立的注释块
使用这些group的标记符号groups也可以嵌套。
如果多次使用一个group标签，将会出错。如果不希望doxygen强行执行唯一标签，可以使用/addtogroup而非/defgroup。运作方式和/defgroup很像，但是如果该group已经定义，它默认向已存在的注释中添加一个新的项。Group的title对此命令是可选的，也可以考虑使用它。
/** /addtogroup <label> */
/*/@{*/
/*/@}*/
这样可以在其他地方以更加详细的说明添加members到一个group
注意compound entities（例如classes，files和namespaces）可以放在多个groups中，但是members（例如variables，functions，typedefs和enmus）只可以归于一个group（这个限制是为了避免链接目标的ambiguous）。
Doxygen将members放在有最高优先级的gourp之中：f.i. /ingroup高于任何使用@{@}的自动归组。和同等的优先级group定义冲突将触发一个警告，除非one definition was for a member without any explicit documentation。下面的例子将VarInA放在group A中，并默认将IntegerVariable放入group IntVariables解决和IntegerVariable的冲突，因为IntegerVariable的第二个instance是未作注释的：
/**
* /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;
/*@}*/
Group定义命令的优先级（从高到低）：/ingroup，/defgroup，/addtogroup，/weakgroup。而/weakgroup很像一个有低优先级的/addtogroup。它被设计为实现一个“lazy”的group定义方法：可以在.h文件中使用高优先级来定义结构，在.cpp文件中使用/weakgroup这样不会重复.h文件中的层次结构。（译注：是否就是说，还可以这样的话还可以在.cpp文件中再作一次group动作？例如，在.cpp文件中又定义了几个nonmember functions，这时可以将使用nonmember function和以前尽管在.h已经做了group的member functions放在一起。）
Example:
/** @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
Click here for the corresponding HTML documentation that is generated by Doxygen.
Member Groups
如果一个compound（例如一个class或file）有多个members，通常我们希望将其group。Doxygen已经可以自动按照类型和protection级别将这些things归组在一起，但可能你会认为仅仅这样是不够的或者这种缺省的方法是错误的。例如你认为有不同（语法）的类型需要归入同一个group（语意）。
这样定义一个member group：
//@{
...
//@}
块或者使用
/*@{*/
...
/*@}*/
块如果你更喜欢C style注释。需要注意的是所有的members必须写在其中。
在//@{之前还可以加一个注释块，这个注释块应该包含@name（或者/name）来指明group的header。可选的，这个注释块可以包含group的更详细的信息。
Member groups不允许使用嵌套。
如果一个类中的某个member group中所有的members有相同的type和protection level（例如都是static public members），那么这整个都会作为该type/protection level group的subgroup显式出来（例如，这个group作为“static public members”section的subsection）。如果两个或更多成员有不同的类型，那么这个group会和自动产生的groups放在同一个level。如果你希望一个类中所有的member-groups都在top level，可以在类的注释块中使用/nosubgrouping命令。
Example:
/** 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();
//@}
Click here for the corresponding HTML documentation that is generated by Doxygen.
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).