分组

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

主题

分组是一种将事物分组在单独页面（称为主题）上的方法。您可以将一个组作为一个整体进行文档记录，也可以记录所有单个成员。组的成员可以是文件、命名空间、类、概念、模块、函数、变量、枚举、typedef 和定义，也可以是其他组。

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

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

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

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

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

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

/** @}*/

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

请注意，复合实体（例如类、文件和命名空间）可以放入多个组中，但是成员（例如变量、函数、typedef 和枚举）只能是一个组的成员（之所以存在此限制是为了避免在成员未在其类、命名空间或文件的上下文中记录，但仅作为组的一部分可见时，出现不明确的链接目标）。

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

以下示例将 VarInA 放入组 A 中，并通过将其放入 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 组 1 中的类 C1 */
class C1 {};
 
/** @brief 组 1 中的类 C2 */
class C2 {};
 
/** 组 1 中的函数 */
void func() {}
 
/** @} */ // group1 结束
 
/**
* @defgroup group2 第二个组
* 这是第二个组
 */
 
/** @defgroup group3 第三个组
* 这是第三个组
 */
 
/** @defgroup group4 第四个组
* @ingroup group3
* 组 4 是组 3 的子组
 */
 
/**
* @ingroup group2
* @brief 组 2 中的类 C3
 */
class C3 {};
 
/** @ingroup group2
* @brief 组 2 中的类 C4
 */
class C4 {};
 
/** @ingroup group3
* @brief @link group3 第三个组@endlink 中的类 C5。
 */
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。

转到下一部分或返回索引。