Doxygen latest release v1.8.3.1 - last update Sat Aug 24 2014

グループ化

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

モジュール

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

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

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

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

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

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

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

/** @}*/

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

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

次の例では、VarInA はグループ A に入り、IntegerVariable は グループIntVariables に入れることで競合を暗黙のうちに解決しています。IntegerVariable の2番目のインスタンスには ドキュメントがないからです。

/**
 * \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 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 コマンドを使って ページにグループ化できます。普通はページの平準なリストができ、 "メイン"ページはリストの最初に来ます。

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

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

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

This page was last modified on Sat Aug 24 2014.
© 1997-2014 Dimitri van Heesch, first release 27 oct 1997.
© 2001 OKA Toshiyuki (Japanese translation).
© 2006-2014 TSUJI Takahiro (Japanese translation).
© 2006-2014 TAKAGI Nobuhisa (Japanese translation).