グループ化

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

モジュール

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

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

ある実体を特定のグループのメンバーにするには、\ingroupコマンドをそのドキュメントブロック内に置きます。

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

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

同じグループラベルを二度使うとエラーメッセージが出ます。 doxygenがユニークなラベルを強制するのを避けるには、\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 コマンドの第一引数は、グループのラベルです。 独自のリンク名を使うには、次に示すように、ラベルの後に二重引用符の間に リンク名を入れてください。

これは、このグループへの \ref グループラベル "リンク" です。

グループ定義の優先度を高い順に示します。 \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 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 は、「公開メンバー」のサブセクションとして表示されています。 また、Group2 は、異なった保護レベル (すなわち、公開および限定公開) にあるメンバーを含んでいるので、独立したセクションになっています。

サブページ

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

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

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

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