分组

Doxygen 有三种机制将事物组合在一起。一种机制在全局层面工作，为每个组创建一个新页面。这些组在文档中被称为'主题'。第二种机制在某个复合实体的成员列表中工作，被称为'成员组'。对于页面，还有第三种分组机制，称为子页。

主题

分组是一种将事物组合在一个单独页面上的方式，这个页面称为主题。你可以将整个组以及所有单独的成员都进行文档化。组的成员可以是文件、命名空间、类、概念、模块、函数、变量、枚举、类型定义和宏定义，也可以是其他组。

要定义一个组，你应该将\defgroup命令放在一个特殊的注释块中。该命令的第一个参数是一个标签，它应该唯一标识该组。第二个参数是该组的名称或标题，它应该出现在文档中。

你可以通过在实体的文档块中放置\ingroup命令，使其成为特定组的成员。

为了避免在每个成员的文档中放置\ingroup命令，你也可以通过在组之前使用开放标记@{并在组之后使用结束标记@}来将成员组合在一起。这些标记可以放在组定义的文档中，也可以放在单独的文档块中。

组本身也可以使用这些分组标记进行嵌套。

当你多次使用相同的组标签时，你会收到错误消息。如果你不希望 Doxygen 强制要求唯一的标签，那么你可以使用\addtogroup而不是\defgroup。它的用法与\defgroup完全相同，但当该组已经定义时，它会静默地将现有文档与新文档合并。该命令的组标题是可选的，所以你可以使用

/** \addtogroup <label>
 *  @{
 */
...

/** @}*/

来向在其他地方更详细定义的组添加额外的成员。

请注意，复合实体（如类、文件和命名空间）可以放在多个组中，但成员（如变量、函数、类型定义和枚举）只能是一个组的成员（此限制是为了避免在成员未在其类、命名空间或文件的上下文中进行文档化，而仅作为组的一部分可见时出现模糊的链接目标）。

Doxygen 会将成员放入定义具有最高“优先级”的组中：例如，显式\ingroup会覆盖通过@{ @}进行的隐式分组定义。具有相同优先级的冲突分组定义会触发警告，除非其中一个定义是针对没有任何显式文档的成员。

以下示例将 VarInA 放入组 A，并通过将 IntegerVariable 放入组 IntVariables 来静默解决 IntegerVariable 的冲突，因为 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;

/**@}*/

\ref命令可用于引用一个组。\ref命令的第一个参数应该是组的标签。要使用自定义链接名称，您可以在标签后用双引号括起来的链接名称，如下例所示

This is the \ref group_label "link" to this group.

分组定义的优先级（从高到低）为：\ingroup、\defgroup、\addtogroup、\weakgroup。\weakgroup命令与\addtogroup完全相同，但优先级较低。添加它是为了允许“惰性”分组定义：您可以在 .h 文件中使用更高优先级的命令来定义层次结构，并在 .c 文件中使用\weakgroup，而无需完全复制层次结构。

示例

/** @defgroup group1 第一个组
* 这是第一个组
 *  @{
 */
 
/** @brief C1 类在组 1 中 */
class C1 {};
 
/** @brief C2 类在组 1 中 */
class C2 {};
 
/** 组 1 中的函数 */
void func() {}
 
/** @} */ // group1 结束
 
/**
* @defgroup group2 第二个组
* 这是第二个组
 */
 
/** @defgroup group3 第三个组
* 这是第三个组
 */
 
/** @defgroup group4 第四个组
* @ingroup group3
* 组 4 是组 3 的子组
 */
 
/**
* @ingroup group2
* @brief C3 类在组 2 中
 */
class C3 {};
 
/** @ingroup group2
* @brief C4 类在组 2 中
 */
class C4 {};
 
/** @ingroup group3
* @brief C5 类在 @link group3 第三个组@endlink。
 */
class C5 {};
 
/** @ingroup group1 group2 group3 group4
* 命名空间 N1 在四个组中
* @sa @link group1 第一个组@endlink, group2, group3, group4
 *
* 另请参阅 @ref mypage2
 */
namespace N1 {};
 
/** @file
* @ingroup group3
* @brief 此文件在组 3 中
 */
 
/** @defgroup group5 第五个组
* 这是第五个组
 *  @{
 */
 
/** @page mypage1 这是组 5 中的一个节
* 第一节的文本
 */
 
/** @page mypage2 这是组 5 中的另一个节
* 第二节的文本
 */
 
/** @} */ // group5 结束
 
/** @addtogroup group1
 *  
* 第一个组的更多文档。
 *  @{
 */
 
/** 组 1 中的另一个函数 */
void func2() {}
 
/** 组 1 中的又一个函数 */
void func3() {}
 
/** @} */ // group1 结束
 

点击此处查看 Doxygen 生成的相应 HTML 文档。

成员组

如果一个复合实体（例如一个类或文件）有许多成员，通常希望将它们组合在一起。Doxygen 已经自动按类型和保护级别将事物组合在一起，但你可能觉得这还不够，或者默认分组是错误的。例如，因为你觉得不同（语法）类型的成员属于同一（语义）组。

一个成员组由一个

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

块或者一个

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

如果你喜欢 C 风格的注释块。请注意，组成员应该物理地位于成员组的主体内部。

在块的开始标记之前，可以放置一个单独的注释块。此块应包含@name（或\name）命令，用于指定组的标题。可选地，注释块还可以包含有关组的更详细信息。

不允许嵌套成员组。

如果一个类中成员组的所有成员都具有相同的类型和保护级别（例如，所有都是静态公共成员），则整个成员组将显示为类型/保护级别组的子组（例如，该组将显示为“静态公共成员”部分的子节）。如果两个或更多成员具有不同的类型，则该组将与自动生成的组处于同一级别。如果您希望强制类的所有成员组都处于顶层，则应在类的文档中放置\nosubgrouping命令。

示例

/** 一个类。详细信息 */
class Memgrp_Test
{
  public:
    ///@{
/** 两个成员的相同文档。详细信息 */
    void func1InGroup1();
    void func2InGroup1();
    ///@}
 
/** 没有组的函数。详细信息。*/
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};
 
void Memgrp_Test::func1InGroup1() {}
void Memgrp_Test::func2InGroup1() {}
 
/** @name 组2
* 组 2 的描述。
 */
///@{
/** 组 2 中的函数 2。详细信息。*/
void Memgrp_Test::func2InGroup2() {}
/** 组 2 中的函数 1。详细信息。*/
void Memgrp_Test::func1InGroup2() {}
///@}
 
/*! \file
* 此文件的文档
 */
 
//!@{
//! 此组所有成员的单一描述
//! （因为配置文件中的 DISTRIBUTE_GROUP_DOC 为 YES）
#define A 1
#define B 2
void glob_func();
//!@}

点击此处查看 Doxygen 生成的相应 HTML 文档。

在此处，Group1 作为“公共成员”的子部分显示。而 Group2 是一个单独的部分，因为它包含具有不同保护级别（即公共和受保护）的成员。

子页

可以使用\page和\mainpage命令将信息分组到页面中。通常，这会产生一个扁平的页面列表，其中“主”页是列表中的第一个。

与主题部分所述的方法不同，通常更自然、更方便使用\subpage命令向页面添加额外的结构。

对于页面 A，\subpage 命令会添加一个指向另一个页面 B 的链接，同时使页面 B 成为页面 A 的子页面。这会产生创建两个组 GA 和 GB 的效果，其中 GB 是 GA 的一部分，页面 A 放在组 GA 中，页面 B 放在组 GB 中。

前往下一节或返回索引。