グルーピング

Doxygen には、項目をグループ化するための 3 つのメカニズムがあります。1 つのメカニズムはグローバルレベルで動作し、グループごとに新しいページを作成します。これらのグループはドキュメントでは「トピック」と呼ばれています。2 番目のメカニズムは、複合エンティティのメンバーリスト内で動作し、「メンバグループ」と呼ばれます。ページの場合、3 番目のグルーピングメカニズムはサブページングと呼ばれます。

トピック

グルーピングは、トピックと呼ばれる別のページで項目をグループ化する方法です。グループ全体とすべての個々のメンバーをドキュメント化できます。グループのメンバーには、ファイル、名前空間、クラス、コンセプト、モジュール、関数、変数、列挙型、typedef、および define だけでなく、他のグループも指定できます。

グループを定義するには、\defgroup コマンドを特別なコメントブロックに記述する必要があります。コマンドの最初の引数は、グループを一意に識別するラベルです。2 番目の引数は、ドキュメントに表示されるグループの名前またはタイトルです。

エンティティを特定のグループのメンバーにするには、\ingroup コマンドをそのドキュメントブロック内に記述します。

各メンバーのドキュメントに \ingroup コマンドを記述するのを避けるために、グループの開始マーカー @{ をグループの前、終了マーカー @} をグループの後に記述して、メンバーをまとめてグループ化することもできます。マーカーは、グループ定義のドキュメントまたは別のドキュメントブロックに記述できます。

グループ自体も、これらのグループ化マーカーを使用してネストできます。

同じグループラベルを複数回使用すると、エラーメッセージが表示されます。Doxygen に一意のラベルを強制させたくない場合は、\defgroup の代わりに \addtogroup を使用できます。\defgroup とまったく同様に使用できますが、グループがすでに定義されている場合、既存のドキュメントを新しいドキュメントと暗黙的にマージします。グループのタイトルはこのコマンドではオプションであるため、次のように使用できます。

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

/** @}*/

他の場所でより詳細に定義されているグループにメンバーを追加します。

複合エンティティ（クラス、ファイル、名前空間など）は複数のグループに含めることができますが、メンバー（変数、関数、typedef、列挙型など）は 1 つのグループのメンバーにしかなれません（この制限は、メンバーがクラス、名前空間、またはファイルのコンテキストでドキュメント化されておらず、グループの一部としてのみ表示される場合に、あいまいなリンクターゲットを回避するために設けられています）。

Doxygen は、定義の「優先度」が最も高いグループにメンバーを配置します。たとえば、明示的な \ingroup は、@{ @} を介した暗黙的なグルーピング定義よりも優先されます。優先度が同じである競合するグルーピング定義は、警告をトリガーします。ただし、1 つの定義が明示的なドキュメントのないメンバーに対するものではない場合は除きます。

次の例では、VarInA をグループ A に配置し、IntegerVariable の 2 番目のインスタンスはドキュメント化されていないため、IntegerVariable をグループ IntVariables に配置することで、競合を暗黙的に解決します。

/**
 * \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 2 番目のグループ
* これは 2 番目のグループです
 */
 
/** @defgroup group3 3 番目のグループ
* これは 3 番目のグループです
 */
 
/** @defgroup group4 4 番目のグループ
* @ingroup group3
* グループ 4 はグループ 3 のサブグループです
 */
 
/**
* @ingroup group2
* @brief グループ 2 のクラス C3 */
 */
class C3 {};
 
/** @ingroup group2
* @brief グループ 2 のクラス C4 */
 */
class C4 {};
 
/** @ingroup group3
* @brief @link group3 3 番目のグループ@endlink のクラス C5。
 */
class C5 {};
 
/** @ingroup group1 group2 group3 group4
* 名前空間 N1 は 4 つのグループに属しています
* @sa @link group1 最初のグループ@endlink、group2、group3、group4 を参照してください
 *
* @ref mypage2 も参照してください
 */
namespace N1 {};
 
/** @file
* @ingroup group3
* @brief グループ 3 のこのファイル
 */
 
/** @defgroup group5 5 番目のグループ
* これは 5 番目のグループです
 *  @{
 */
 
/** @page mypage1 グループ 5 のセクション 1
* セクション 1 のテキスト
 */
 
/** @page mypage2 グループ 5 のセクション 2
* セクション 2 のテキスト
 */
 
/** @} */ // group5 の終わり
 
/** @addtogroup group1
 *  
* 最初のグループの追加ドキュメント。
 *  @{
 */
 
/** グループ 1 の別の関数 */
void func2() {}
 
/** グループ 1 のさらに別の関数 */
void func3() {}
 
/** @} */ // group1 の終わり
 

こちらをクリックすると、Doxygen によって生成された対応する HTML ドキュメントが表示されます。

メンバグループ

複合 (クラスやファイルなど) に多数のメンバーがある場合、それらをグループ化することが望ましい場合があります。Doxygen はすでにタイプと保護レベルで項目を自動的にグループ化していますが、これでは不十分であると感じたり、デフォルトのグルーピングが間違っていると感じたりする場合があります。たとえば、異なる (構文的な) タイプのメンバーが同じ (意味的な) グループに属していると感じる場合などです。

メンバグループは、

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

ブロックまたは

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

C スタイルのコメントを使用する場合はブロックによって定義されます。グループのメンバーは、メンバグループの本体内に物理的に存在する必要があることに注意してください。

ブロックの開始マーカーの前に、別のコメントブロックを配置できます。このブロックには、@name (または \name) コマンドを含める必要があり、グループのヘッダーを指定するために使用されます。オプションで、コメントブロックにはグループに関するより詳細な情報を含めることもできます。

メンバグループのネストは許可されていません。

クラス内のメンバグループのすべてのメンバーが同じタイプと保護レベル (たとえば、すべてが static public メンバー) を持つ場合、メンバグループ全体がタイプ/保護レベルグループのサブグループとして表示されます (グループは、たとえば「Static Public Members」セクションのサブセクションとして表示されます)。2 つ以上のメンバーが異なるタイプを持っている場合、グループは自動的に生成されたグループと同じレベルに配置されます。クラスのすべてのメンバグループをトップレベルに強制的に配置する場合は、クラスのドキュメント内に \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
* このファイルのドキュメント
 */
 
//!@{
//! このグループのすべてのメンバーに対する 1 つの説明
//! (config ファイルで DISTRIBUTE_GROUP_DOC が YES になっているため)
#define A 1
#define B 2
void glob_func();
//!@}

こちらをクリックすると、Doxygen によって生成された対応する HTML ドキュメントが表示されます。

ここでは、Group1 は「Public Members」のサブセクションとして表示されます。また、Group2 は、異なる保護レベル (つまり、public と protected) のメンバーが含まれているため、別のセクションになります。

サブページング

情報は、\page および \mainpage コマンドを使用してページにグループ化できます。通常、これによりページのフラットリストが作成され、「メイン」ページがリストの最初になります。

セクション トピック で説明されているアプローチを使用して構造を追加する代わりに、\subpage コマンドを使用してページに追加の構造を追加する方が、多くの場合、より自然で便利です。

ページ A の場合、\subpage コマンドは別のページ B へのリンクを追加すると同時に、ページ B をページ A のサブページにします。これにより、GA と GB の 2 つのグループが作成され、GB は GA の一部となり、ページ A はグループ GA に配置され、ページ B はグループ GB に配置されます。

次のセクションに進むか、インデックスに戻ります。