分组

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

主题

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

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

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

为了避免在每个成员的文档中都放入\ingroup命令，您也可以使用组前的开放标记@{和组后的结束标记@}来将成员分组。标记可以放在组定义的文档中，也可以放在单独的文档块中。

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

当您多次使用相同的组标签时，您会收到错误消息。如果您不希望 Doxygen 强制执行唯一标签，则可以使用\addtogroup代替\defgroup。它的用法与\defgroup完全相同，但当组已定义时，它会静默地将现有文档与新文档合并。对于此命令，组的标题是可选的，因此您可以使用

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

/** @}*/

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

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

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

以下示例将 VarInA 放入组 A，并通过将 IntegerVariable 放入组 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;

/**@}*/

命令\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 Group2
* 组 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 中。

前往下一节或返回索引。