モジュールは、独立した1つのページ上に事物をまとめてグループ化するための方法です。 個々のメンバーと同様、グループそのものにもドキュメント付けをすることができます。 グループに属するメンバーには、ファイル、名前空間、クラス、関数、 変数、enum、typedef、define があります。また、他のグループが メンバーになることもできます。
グループを定義するには、専用コメントブロック内に、 \defgroup コマンドを置く必要があります。 コマンドの最初の引数は、グループを一意に識別するためのラベルです。 ある実体のドキュメントブロック内に \ingroup コマンドを置くことにより、その実体を特定のグループのメンバーにすることができます。 2番目の引数は、グループのタイトルです。
各メンバーのドキュメントに \ingroup を置くのを避けるために、 グループの前に置いた開標識 @{ とグループの後に置いた閉標識 @} によって、 メンバーをまとめてグループ化することもできます。 標識は、グループ定義のドキュメントに置いてもよいし、 独立のドキュメントブロックに置いてもかまいません。
グループは、このグループ化標識を使ってネストすることもできます。
同じグループラベルを2回以上使用すると、エラーメッセージが出ます。 doxygen に一意的なラベルを強制してほしくない場合は、 \defgroup の代わりに、\addtogroup を使うことができます。 これは、\defgroup と全く同じように使うことができますが、 グループがすでに定義済みのときは、暗黙のうちに、 既存のドキュメントを新しいものとマージしてしまいます。 このコマンドでは、グループのタイトルはオプションです。したがって、
/** \addtogroup <ラベル> */
/*\@{*/
/*\@}*/
複合的 (compound) 実体 (クラス、ファイル、名前空間など) は、 複数のグループに置くことができますが、 メンバー (変数、関数、typedef、enumなど) は、 1つのグループにしか属せません (この制限は、リンクターゲットが曖昧になるのを避けるためです)。
doxygen は、最高の優先度を持ったグループ化定義で指定されるグループに、 メンバーを置きます: たとえば、\ingroup は、 @{ @} によるどんな自動グループ化定義も上書きします。 同じ優先度を持つグループ化定義が衝突すると、 一方の定義が、明示的なドキュメントを何も持たないようなメンバーに対するものでないかぎり、 警告が出されます。 次の例では、VarInA をグループ A に置いています。 また、IntegerVariable の衝突を暗黙のうちに解決して、 それをグループ IntVariables に置いています。 その理由は、IntegerVariable の 2番目の出現にはドキュメント付けがなされていないからです。
/**
* \ingroup A
*/
extern int VarInA;
/**
* \defgroup IntVariables グローバルな整数変数
*/
/*@{*/
/** 整数変数 */
extern int IntegerVariable;
/*@}*/
....
/**
* \defgroup Variables グローバル変数
*/
/*@{*/
/** グループ A の変数 */
int VarInA;
int IntegerVariable;
/*@}*/
グループ化定義の優先度は、次のとおり (最高から最低へ): \ingroup、\defgroup、 \addtogroup、\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
複合体 (compound; たとえば、クラスやファイル) が数多くのメンバーを持っているとき、 しばしば、それらをまとめてグループ化したくなります。 doxygen は、すでに型や保護レベルに基づいて事物を自動的にグループ化しているのですが、 ユーザとしては、グループ化が十分でなかったり、あるいは間違っていると 感じることがあるかもしれません。 たとえば、(構文的に) 型の異なるメンバーが、 (意味的に) 同じグループに属している、という理由で。
メンバーグループは、
//@{
...
//@}
/*@{*/
...
/*@}*/
ブロックの開標識の前に、独立したコメントブロックを置くこともできます。 このブロックは、@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();
//@}
ここで、Group1 は、「公開メンバー」のサブセクションとして表示されています。 また、Group2 は、異なった保護レベル (すなわち、公開および限定公開) にあるメンバーを含んでいるので、独立したセクションになっています。
1.2.11.1 の開発者: Dimitri van Heesch,
© 1997-2001