グループ化

doxygen には、物事をまとめてグループ化するためのメカニズムが 3つあります。 1つ目は、グローバルなレベルで動作して、各グループごとに新しいページを作成します。 これらのグループは、ドキュメントでは「モジュール」と呼ばれています。 2つ目のメカニズムは、何らかの複合体 (compound) に属するメンバーリスト内で動作するものであり、 「メンバーグループ」と呼ばれています。 ページに対して、サブページ化を扱う 3つ目のメカニズムがあります。

モジュール

モジュールは、独立した1つのページ上に事物をまとめてグループ化するための方法です。 個々のメンバーと同様、グループそのものにもドキュメント付けをすることができます。 グループに属するメンバーには、ファイル、名前空間、クラス、関数、 変数、enum、typedef、define があります。また、他のグループが メンバーになることもできます。

グループを定義するには、専用コメント・ブロック内に、 \defgroup コマンドを置く必要があります。 コマンドの最初の引数は、グループを一意に識別するためのラベルです。 2番目の引数は、ドキュメントに現れる、グループの名前またはタイトルです。

コマンドを置くことにより、その実体を特定のグループのメンバーにすることができます。

各メンバーのドキュメントに \ingroup を置くのを避けるために、 グループの前に置いた開標識 @{ とグループの後に置いた閉標識 @} によって、 メンバーをまとめてグループ化することもできます。 標識は、グループ定義のドキュメントに置いてもよいし、 独立のドキュメントブロックに置いてもかまいません。

グループそのものも、これらグループ化用ラベルを使ってネストできます。

同じグループラベルを二度使うとエラーメッセージが出ます。 ユニークなラベルを使わないようにするには、\defgroup でなく \addtogroup を使えます。 これは \defgroup と同様な使い方ができますが、 グループが既に定義されている場合には、暗黙のうちに既存のドキュメントと 新しいドキュメントをマージします。 このコマンドではグループのタイトルはオプションなので、他でより細かく 定義されているグループにメンバーを追加するには、次のようにできます。

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

複合要素 (クラス、ファイル、名前空間) は、複数のグループに挿入できますが、 メンバー (変数、関数、型定義、列挙型) は１グループのメンバーにしかなれません。 (この制限は、メンバーが、その属するクラス、名前空間、ファイルの文脈中では ドキュメント付けされていないがグループの一部としては現れる場合に、 あいまいなリンクを避けるのに有用です)

doxygen は、定義の "優先度" が最も高いグループにメンバーを属させます。 例えば、明示的な \ingroup は、 @{ @} を介して暗黙のグループ定義を無効化します。 優先度が同じグループ定義が競合する場合、一方のメンバーに明示的なドキュメントが ない限り、警告を起こします。

次の例では、VarInA はグループ A に入り、IntegerVariable を IntVariables に入れることで問題を自動的に解決しています。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 command コマンドの第一引数は、グループのラベルです。 custom リンク名を使うには、次に示すように、ラベルの後に二重引用符の間に リンク名を入れてください。

This is the \ref group_label "link" to this group.

グループ定義の優先度を高い順に示します。 \ingroup, \defgroup, \addtogroup, \weakgroup 最後のコマンドは、\addtogroup とよく似ていますが、 優先度は低いです。このコマンドは "lazy(ゆるい)" グループ定義ができるように追加 されました。序列を定義するには .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

この例に対する HTML ドキュメントを見るには、ここ をクリックしてください。

メンバーグループ

複合体 (compound; たとえば、クラスやファイル) が数多くのメンバーを持っているとき、 しばしば、それらをまとめてグループ化したくなります。 doxygen は、すでに型や保護レベルに基づいて事物を自動的にグループ化しているのですが、 ユーザとしては、グループ化が十分でなかったり、あるいは間違っていると 感じることがあるかもしれません。 たとえば、(構文的に) 型の異なるメンバーが、 (意味的に) 同じグループに属している、という理由で。

メンバーグループは、

//@{ 
  ...
//@}

というブロック、または、Cスタイルのコメントを好むなら、

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

というブロックによって定義されます。グループのメンバーは、 物理的に、メンバーグループの本体内に存在する必要があるということに注意してください。

ブロックの開標識の前に、独立したコメント・ブロックを置くこともできます。 このブロックは、@name (または、\name) コマンドを含む必要があり、グループのヘッダーを指定します。 そうしたければ、グループに関するより詳しい情報をコメント・ブロックに含めることもできます。

メンバーグループはネストできません。

クラス内のあるメンバーグループに属する全メンバーが、 同じ型を持ち、かつ同じ保護レベル (たとえば、すべてが静的な公開メンバー) にある場合、 そのメンバーグループ全体が、その型/保護レベルのグループのサブグループとして表示されます (たとえば、そのグループは、 「静的な公開メンバー」セクションのサブセクションとして表示される)。 2つ以上のメンバーが異なる型を持つ場合は、グループは、 自動的に生成されるグループと同じレベルに置かれます。 もし、クラス内の全メンバーグループがトップレベルになるよう強制したいのなら、 クラスのドキュメントの内部に、 \nosubgrouping コマンドを置く必要があります。

例:

/** A class. Details */
class Test
{
  public:
    //@{
    /** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    //@}

    /** Function without group. Details. */
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};

void Test::func1InGroup1() {}
void Test::func2InGroup1() {}

/** @name Group2
 *  Description of group 2. 
 */
//@{
/** Function 2 in group 2. Details. */
void Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void 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 は、「公開メンバー」のサブセクションとして表示されています。 また、Group2 は、異なった保護レベル (すなわち、公開および限定公開) にあるメンバーを含んでいるので、独立したセクションになっています。

サブページ

情報は、\page と \mainpage コマンドを使って ページにグループ化できます。普通はページの平準なりストができ、 "メイン"ページはリストの最初になります。

セクション modules で述べた方法を使って構造体を加えるより、 \subpage コマンドを使ってページに構造体を加えるほうが、 自然で便利です。

ページAについて、\subpage コマンドは他のページBへのリンクを作り、同時に ページBはページAのサブページとなります。これによって、グループGA,GBができ、 GBはGAの一部で、ページAはグループGA、ページBはグループGBに属します。

次 のセクションに行く / インデックス に戻る