グルーピング

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

トピック

グルーピングとは、トピックと呼ばれる個別のページに複数のものをまとめてグループ化する方法です。グループ全体を文書化することも、個々のメンバをすべて文書化することもできます。グループのメンバには、ファイル、名前空間、クラス、コンセプト、モジュール、関数、変数、列挙型、typedef、defineなどが含まれますが、他のグループも含まれます。

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

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

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

これらのグルーピングマーカーを使用すると、グループ自体をネストすることもできます。

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

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

/** @}*/

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

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

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

以下の例では、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 The First Group
* This is the first group
 *  @{
 */
 
/** @brief class C1 in group 1 */
class C1 {};
 
/** @brief class C2 in group 1 */
class C2 {};
 
/** function in group 1 */
void func() {}
 
/** @} */ // end of group1
 
/**
* @defgroup group2 The Second Group
* This is the second group
 */
 
/** @defgroup group3 The Third Group
* This is the third group
 */
 
/** @defgroup group4 The Fourth Group
* @ingroup group3
* Group 4 is a subgroup of group 3
 */
 
/**
* @ingroup group2
* @brief class C3 in group 2
 */
class C3 {};
 
/** @ingroup group2
* @brief class C4 in group 2
 */
class C4 {};
 
/** @ingroup group3
* @brief class C5 in @link group3 the third group@endlink.
 */
class C5 {};
 
/** @ingroup group1 group2 group3 group4
* namespace N1 is in four groups
* @sa @link group1 The first group@endlink, group2, group3, group4
 *
* Also see @ref mypage2
 */
namespace N1 {};
 
/** @file
* @ingroup group3
* @brief this file in group 3
 */
 
/** @defgroup group5 The Fifth Group
* This is the fifth group
 *  @{
 */
 
/** @page mypage1 This is a section in group 5
* Text of the first section
 */
 
/** @page mypage2 This is another section in group 5
* Text of the second section
 */
 
/** @} */ // end of group5
 
/** @addtogroup group1
 *  
* More documentation for the first group.
 *  @{
 */
 
/** another function in group 1 */
void func2() {}
 
/** yet another function in group 1 */
void func3() {}
 
/** @} */ // end of group1
 

Doxygenによって生成された対応するHTMLドキュメントはこちらをクリックしてください。

メンバグループ

複合体（クラスやファイルなど）に多くのメンバがある場合、それらをまとめてグループ化したいと考えることがよくあります。Doxygenはすでに型と保護レベルに基づいて自動的にグループ化を行いますが、これが十分でない、またはデフォルトのグループ化が間違っていると感じるかもしれません。たとえば、異なる（構文的な）型のメンバが同じ（意味的な）グループに属すると感じる場合などです。

メンバグループは、

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

ブロック、または

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

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

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

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

クラス内のメンバグループのすべてのメンバが同じ型と保護レベルを持つ場合（例えば、すべてが静的パブリックメンバである場合）、メンバグループ全体は型/保護レベルグループのサブグループとして表示されます（たとえば、「Static Public Members」セクションのサブセクションとしてグループが表示されます）。2つ以上のメンバが異なる型を持つ場合、そのグループは自動生成されたグループと同じレベルに配置されます。クラスのすべてのメンバグループを最上位レベルに強制したい場合は、クラスのドキュメント内に\nosubgroupingコマンドを配置する必要があります。

例

/** A class. Details */
class Memgrp_Test
{
  public:
    ///@{
/** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    ///@}
 
/** Function without group. Details. */
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};
 
void Memgrp_Test::func1InGroup1() {}
void Memgrp_Test::func2InGroup1() {}
 
/** @name Group2
* Description of group 2.
 */
///@{
/** Function 2 in group 2. Details. */
void Memgrp_Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void Memgrp_Test::func1InGroup2() {}
///@}
 
/*! \file
* docs for this file
 */
 
//!@{
//! one description for all members of this group
//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)
#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のサブページにします。これにより、GBがGAの一部である2つのグループGAとGBが作成され、ページAはグループGAに、ページBはグループGBに配置される効果があります。

次のセクションへ移動するか、インデックスに戻ります。