doxygen では、以下のようなタイプの専用ドキュメントブロックがサポートされています:
/*! ... テキスト ... */
//! ... 一行のテキスト ...
/** * ... テキスト ... */
/// ... 一行のテキスト ...
これは、Qt スタイルでドキュメントを記述した、C++ コードの例です:
//! A test class.
/*!
A more elaborate class description.
*/
class Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
//! A constructor.
/*!
A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};
一行のコメントは、簡易記述を含んでいるべきです。 一方、複数行のコメントブロックは、より詳細な記述を含むべきです。 連続した一行コメントは、マージされて、 1つの簡易記述にまとめられてしまうということに注意してください。 簡易記述は、クラスや名前空間、ファイルに属するメンバー総覧で使用され、 小さなイタリック体のフォントで表示されます (この記述は、設定ファイルで、BRIEF_MEMBER_DESC を NO に設定すると表示されなくなります)。 デフォルトでは、簡易記述は、詳細記述の最初の文になります (しかし、これは REPEAT_BRIEF タグを NO に設定することで変えることができます)。 Qt スタイルでは、簡易記述と詳細記述の両方ともがオプションです。
JavaDoc スタイルのドキュメントブロックは、デフォルトでは、 Qt スタイルのドキュメントブロックと同じように振る舞います。 しかしながら、これは、JavaDoc の仕様に合致していません。 JavaDoc では、ドキュメントブロックの最初の行は、自動的に簡易記述として扱われます。 この振る舞いを可能にするには、設定ファイルで、 JAVADOC_AUTOBRIEF を YES に設定する必要があります。 このオプションを有効にした上で、文を終わらせずに、 その途中にドットを置きたい場合は、ドットの後にバックスラッシュと空白を 入れる必要があります。 例:
/** Brief description (e.g.\ using only a few words). Details follow. */
上に示したものと同じコードですが、今度は、JavaDoc スタイルで、 JAVADOC_AUTOBRIEF を YES に設定したもの:
/**
* A test class. A more elaborate class description.
*/
class Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
他の大多数のドキュメンテーションシステムとは異なり、 doxygen では、(グローバルな関数も含め) メンバー定義の前のところに ドキュメントを置くこともできます。 このことによって、ヘッダーファイルではなく、 ソースファイルにドキュメントを置くことが可能になります。 ヘッダーファイルはコンパクトに保たれ、 また、メンバーの実装者は、より直接的にドキュメントにアクセスすることが できるようになるのです。
折衷案として、宣言の前に簡易記述を置き、 メンバー定義の前に詳細記述を置いてもよいでしょう。
ここまでは、ドキュメントブロックが常に、ファイル、クラス、名前空間、 もしくは、それらに属するメンバーの、宣言あるいは定義の前に置かれるという 仮定をしてきました。 たいていはこれでうまくゆくのですが、 時にはドキュメントを別の場所に置いたほうがよい場合もあります。 いくつかのタイプのドキュメントブロック (ファイルドキュメントのような) では、そうすることが必須ですらあります。 doxygen では、ドキュメントブロックの内部に構造化コマンドを置きさえすれば、 実際上、どこにでもドキュメントブロックを置くことができます (例外は、関数本体の内部または通常の C スタイルのコメントブロックの内部)。
(他のすべてのコマンドと同様) 構造化コマンドは、バックスラッシュ (\) ―― JavaDoc スタイルでは、アットマーク (@) ―― で始まり、 その後にコマンド名と1つ以上の引数が続きます。 たとえば、上の例で、クラス Test をドキュメント付けしたいとしましょう。 その場合、doxygen によって読み込まれる入力のどこかに、 次のようなドキュメントブロックを置いてもよいのです:
/*! \class Test
\brief A test class.
A more detailed class description.
*/
ここで、専用コマンド \class は、コメントブロックがクラス Test のドキュメントを格納していることを示すのに使われています。 他にも次のような構造化コマンドがあります:
\struct … C 構造体に対するドキュメント \union … 共用体に対するドキュメント \enum … 列挙型に対するドキュメント \fn … 関数に対するドキュメント \var … 変数、typedef、または列挙型の値に対するドキュメント \def … #define に対するドキュメント \file … ファイルに対するドキュメント \namespace … 名前空間に対するドキュメント C++ のクラスメンバーをドキュメント付けするには、 そのクラス自身もドキュメント付けしなければなりません。 同じことが、名前空間にも当てはまります。 グローバルな C 関数、typedef、enum あるいはプリプロセッサ定義を ドキュメント付けするには、まず、それを含むファイルをドキュメント付けしなければなりません (通常、これはヘッダーファイルです。 というのも、それは他のソースファイルにエクスポートされる情報を格納しているからです)。
これはしばしば見落とされるので、繰り返しておきましょう: グローバルオブジェクト (関数、typedef、enum、マクロなど) をドキュメント付けするには、 それらが定義されているファイルをドキュメント付けしなければなりません。 言葉をかえると、このファイルには、少なくとも、
/*! \file */
/** @file */
これは、構造化コマンドを使ってドキュメント付けされた、 structcmd.h という名前の C ヘッダーファイルの例です:
/*! \file structcmd.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
\param fd The descriptor to write to.
\param buf The data buffer to write.
\param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
ファイル、構造体、共用体、クラス、あるいは列挙型のメンバーをドキュメント付けしたい、 しかも、これらのメンバーに対するドキュメントを複合体 (compound) の内部に置きたいという場合は、 メンバーの前ではなく、メンバーの後にドキュメントブロックを置くことが望ましいこともあります。 このような目的のために、doxygen には、以下のような特別なコメントブロックがあります:
/*!< ... */
//!< ...
/**< ... */
JAVADOC_AUTOBRIEF が YES に設定されていると、 最初の文は簡易記述になります) また、別に、簡易記述もあります: ///< ...
以下は、これらのコメントブロックを使用している例です:
/*! A test class */
class Test
{
public:
/** An enum type.
* The documentation block cannot be put after the enum!
*/
enum EnumType
{
int EVal1, /**< enum value 1 */
int EVal2 /**< enum value 2 */
};
void member(); //!< a member function.
protected:
int value; /*!< an integer value */
};
\class のような) は、 これらのコメントブロックの内では無視されます。
1.2.11.1 の開発者: Dimitri van Heesch,
© 1997-2001