群組化

Doxygen 有三種機制可以將事物群組在一起。一種機制在全域層級運作，為每個群組建立一個新頁面。這些群組在文件中稱為 「主題」。第二種機制在某個複合實體的成員列表中運作，稱為「成員群組」。對於頁面，還有第三種群組機制，稱為子頁面。

主題

群組化是一種將事物在獨立頁面（稱為主題）上群組在一起的方法。您可以將群組整體記錄下來，也可以記錄所有個別成員。群組的成員可以是檔案、命名空間、類別、概念、模組、函式、變數、列舉、typedef 和 define，也可以是其他群組。

若要定義群組，您應該在特殊的註解區塊中放入 \defgroup 命令。命令的第一個引數是一個標籤，應該唯一識別群組。第二個引數是群組的名稱或標題，它應顯示在文件中。

您可以將實體設為特定群組的成員，方法是在其文件區塊內放入 \ingroup 命令。

為避免在每個成員的文件中放入 \ingroup 命令，您也可以將成員群組在一起，方法是在群組之前使用開頭標記 @{，並在群組之後使用結尾標記 @}。這些標記可以放在群組定義的文件中，或放在獨立的文件區塊中。

群組本身也可以使用這些群組標記來巢狀結構化。

當您多次使用相同的群組標籤時，會收到錯誤訊息。如果您不希望 Doxygen 強制執行唯一的標籤，則可以使用 \addtogroup，而不是 \defgroup。它的使用方式與 \defgroup 完全相同，但是當群組已定義時，它會默默地將現有的文件與新的文件合併。群組的標題對於此命令是可選的，因此您可以使用

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

/** @}*/

將其他成員新增到在其他地方更詳細定義的群組。

請注意，複合實體（如類別、檔案和命名空間）可以放入多個群組中，但成員（如變數、函式、typedef 和列舉）只能是一個群組的成員（此限制是為了避免在成員未在其類別、命名空間或檔案的內容中記錄，而僅作為群組的一部分可見時，產生不明確的連結目標）。

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 群組 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 中。

前往下一節或返回索引。