グループ化

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

トピック

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

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

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

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

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

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

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

/** @}*/

をどこかでより詳細に定義されているグループに、追加のメンバーを追加するために使用できます。

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

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

次の例では、VarInA をグループ A に配置し、IntegerVariable の2番目のインスタンスがドキュメント化されていないため、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のセクションです
* 最初のセクションのテキスト
 */
 
/** @page mypage2 これはグループ5の別のセクションです
* 2番目のセクションのテキスト
 */
 
/** @} */ // group5の終わり
 
/** @addtogroup group1
 *  
* 最初のグループに関する追加のドキュメント。
 *  @{
 */
 
/** グループ1の別の関数 */
void func2() {}
 
/** グループ1のさらに別の関数 */
void func3() {}
 
/** @} */ // group1の終わり
 

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

メンバーグループ

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

メンバーグループは

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

ブロック、または

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

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

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

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

クラス内のメンバーグループのすべてのメンバーが同じ型と保護レベルを持つ場合（たとえば、すべてが静的パブリックメンバーである場合）、メンバーグループ全体は型/保護レベルグループのサブグループとして表示されます（たとえば、「静的パブリックメンバー」セクションのサブセクションとして表示されます）。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つの説明
//! (設定ファイルでDISTRIBUTE_GROUP_DOCがYESのため)
#define A 1
#define B 2
void glob_func();
//!@}

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

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

サブページ化

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

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

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

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