|
latest release v1.8.11 - last update Mon Oct 25 2021 | |
|
目次コードのドキュメント付けこの章では、2つのテーマを取り上げます。
特殊なコメントブロック特殊コメントブロックは、C または C++スタイルのコメントブロックにマークを付け加えたもので、Doxygenはこれを構造化されたテキスト断片と認識して、ドキュメントを生成します。次 セクションでは、doxygenがサポートするさまざまなスタイルを示します。 Python,VHDL,Fortran,Tcl コードについては、別のコメント表記規則があります。セクションPython でのコメント・ブロック, VHDL でのコメント・ブロック, Fortranでのコメント・ブロック, Tclでのコメントブロック で説明します。 C系統の言語のコメントブロック (C/C++/C#/Objective-C/PHP/Java)各コード要素について、説明形式が2（3の場合も）種類あり、これらが該当要素のドキュメントを形成します。それは、要約説明 と 詳細説明 で、どちらもオプションです。メソッドと関数については、もうひとつの形式があり、いわゆる"本文内"説明で、メソッドや関数の本体内のコメントブロックの連結からなります。 ひとつ以上の要約説明または詳細説明を指定できます。（ただし、出現順序が指定されていないためお勧めできません。） 名前からわかるように、要約説明は短い一行ですが、詳細説明はより長く、より詳しいドキュメントを提供します。"本文内"説明も詳細説明となりますが、こちらは実装の詳細をまとまって説明することができます。HTML出力の場合、要素が参照されている箇所で要約説明を使えばツールチップを提供できます。 コメント・ブロックに詳細説明のマークを付ける方法を示します。
要約説明にも、いくつかのやり方があります。
このように、Doxygenの自由度は高いです。詳細説明が次のように複数あったら //! 要約説明でも、 //! 複数行にわたれば実際は詳細説明 /*! お、また別の詳細説明だ! */ これらは一緒になります。コードの中で説明が散らばっていることもありますが同じです。その場合、順序はDoxygenのコード解析の順序に依存します。 他の多くのドキュメンテーションシステムとは違い、doxygenでは、メンバー(グローバル関数を含む)のドキュメントを、定義 の前に置くことができます。この方法を使うと、ドキュメントがヘッダファイルでなく、ソースファイルに置けます。これによりヘッダファイルはコンパクトなままにでき、メンバーの作成者が直接ドキュメントにアクセスできます。妥協案として、要約説明を宣言の前に、詳細説明をメンバー定義の前に置くことができます。 メンバーの後ろにドキュメントを置くファイル、構造体、共用体、クラス、enumのメンバーにドキュメントをつけたい場合、メンバーの前でなく後ろにドキュメントブロックを置くほうが望ましい場合があります。そのためには、< マーカーをコメントブロックにつける必要があります。これは、関数の引数にも応用できます。 いくつか例を挙げます。 int var; /*!< メンバーの後ろの詳細説明 */ このブロックは、Qtスタイルの詳細ドキュメントブロックをメンバーの 後ろ に置く場合に使えます。同じことを他の方法ですると、 int var; /**< メンバーの後ろの詳細説明 */ または int var; //!< メンバーの後ろの詳細説明
//!<
または int var; ///< メンバーの後ろの詳細説明
///<
メンバーの後ろに要約説明を置きたいこともよくあります。 これは次のようにします。 int var; //!< メンバーの後ろの要約説明 または int var; ///< メンバーの後ろの要約説明 関数に対しては、@param コマンドを使って、引数のドキュメントを書けます。方向を示すには、 void foo(int v /**< [in] 入力引数vのドキュメント */); これらのブロックは、前のセクションの特殊コメントブロックと同じ構造と意味を持っています。< だけが、メンバーがブロックの後ろでなく前にあることを示しています。 これらのコメントブロックの使用例を示します。 /*! A test class */
class Afterdoc_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 */
};
例以下は、Qt スタイルを使った C++ コードのドキュメント付けされた断片の例です。 //! A test class.
/*!
A more elaborate class description.
*/
class QTstyle_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.
*/
QTstyle_Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~QTstyle_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 QTstyle_Test(), ~QTstyle_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);
};
要約説明は、クラスや名前空間、ファイルに属するメンバー総覧で使用され、小さな斜体のフォントで表示されます(この説明は、設定ファイルで、BRIEF_MEMBER_DESCを JavaDoc スタイルのドキュメント・ブロックは、デフォルトでは、Qt スタイルのドキュメントブロックと同じように振る舞います。 しかしながら、これは、JavaDoc の仕様に合致していません。 JavaDoc では、ドキュメントブロックの最初のセンテンスは、自動的に要約説明として扱われます。 要約説明として機能させるには、設定ファイルで、JAVADOC_AUTOBRIEF を /** 詳細説明 (例.\ 語は少しだけ). 詳細が続く. */ 次の例は上に示したものと同じコードですが、今度は、JavaDoc スタイルで、JAVADOC_AUTOBRIEF を /**
* A test class. A more elaborate class description.
*/
class Javadoc_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.
*/
Javadoc_Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Javadoc_Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Javadoc_Test()
* @see ~Javadoc_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);
};
同様に、Qtスタイルのドキュメントブロックの最初のセンテンスを自動的に要約説明として扱うには、設定ファイルで QT_AUTOBRIEF をYESに設定します。 他の場所のドキュメントここまでは、ドキュメント・ブロックは常にファイル、クラス、名前空間の宣言または定義の 前に 、あるいはメンバーの 前後 にあるものとしていました。 この方が都合の良いことが多いのですが、他の場所にドキュメントを置きたいといったこともありえます。ファイルの場合、"ファイルの前に"というわけにはいかないので、この方法をとります。 Doxygen では、実際他の場所にドキュメント・ブロックを置けます。(例外:関数の本体内部、普通のCスタイルコメントブロック内部) ドキュメント・ブロックを要素のすぐ前後に置かない場合には、構造化コマンドをドキュメント・ブロック内部に指定する必要があります。 この場合、情報が二重定義になりかねません。ですので、実際には他の理由で仕方 ない限り は、構造化コマンドの使用は 避けたい ところです。 構造化コマンドは (特殊コマンドと同様) バックスラッシュ ( /*! \class Test
\brief test クラス
クラスの詳細説明
*/
ここで特殊コマンド
これら多くのコマンドについての詳しい情報は、特殊コマンドをご覧ください。 C++ クラスのメンバーをドキュメント付けするには、クラス自体もドキュメント付けする必要があります。 名前空間にも同じことが言えます。グローバルな 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);
このファイルの中のコメントブロックそれぞれに、構造化コマンドが含まれているため、 コメントブロックはすべて、生成されるドキュメントには影響を及ぼさずに、他の場所や 入力ファイル (たとえばソースファイル) に移動できます。 ただし、この方法ではプロトタイプが二重となるため、変更はすべて２回しなければならない という欠点があります。このため、先ずは本当に必要か考え、できれば構造化コマンドは避けた ほうがいいでしょう。関数の前に置かれたコメントブロックに \fn コマンドがある例をときどき 見かけます。\fn コマンドは冗長なので、問題が起こるのは明らかです。 拡張子 Doxygenが解析できないファイルをどうしてもドキュメント化したい場合は、\verbincludeを使えば、生で表示できます。 /*! \file myscript.sh * 以下のスクリプトを見てください: * \verbinclude myscript.sh */ INPUTにスクリプトを明確に指定するか、あるいは、FILE_PATTERNS に拡張子 Python でのコメント・ブロックPython では、コードをドキュメント付けするのにいわゆるドキュメント文字列を使用する方法が標準化されています。この文字列は、 このケースでは、doxygen の特殊コマンドはどれもサポートされないことに 注意してください。 以下は、再度同じ例ですが、今度は doxygen スタイルのコメントを使っています。 Python は、見た目が C や C++ よりJava に似ているので、設定ファイルでは OPTMIZE_OUTPUT_JAVA を VHDL でのコメント・ブロックVHDLのコメントは普通 "–"で始まります。Doxygenは"–!"で始まるコメントを抽出します。VHDLには次の2種類のコメントブロックしかありません。一行の "–!" コメントは要約説明を、複数の "–!" コメント("–!" が各行で前置きされます)は詳細説明を表します。 コメントは常に、ドキュメントつき要素の前に配置されます。例外として、ポートではコメントは要素の後ろにも置くことが可能で、ポートの要約説明として扱います。 DoxygenコメントのついたVHDLファイルを示します。 見栄えのいい出力を得るには、設定ファイルで OPTIMIZE_OUTPUT_VHDL を Fortranでのコメント・ブロックFortranコードにdoxygenを使うときは、OPTIMIZE_FOR_FORTRANをYESに設定してください。 パーサーは、ソースコードが固定形式Fortranなのか自由形式Fortranなのかをコードから推測しますが、必ずしも正確ではありません。もし正確でないなら、EXTENSION_MAPPINGを使ってください。 Fortranでは、"!>"、"!<" はコメントの始まりで、複数行に分けるには、"!!"、"!>"を使います。 次は、ドキュメントつきFortranサブルーチンの例です。 !> 集合のために制約配列を
!! 構築する
!! @param aggr 集合についての情報
!! @todo 特殊ケースを扱う
subroutine intrestbuild(A,aggr,Restrict,A_ghost)
implicit none
Type(spmtx), intent(in) :: a !< 配列
type(aggrs), intent(in) :: aggr
Type(spmtx), intent(out) :: restrict !< 制約配列
!...
end subroutine
あるいは、定型コードでコメントを使うこともできます。 C> 関数コメント
C> 次のコメント行
function A(i)
C> 入力引数
integer i
end function A
Tclでのコメントブロック通常のTclコメント内にdoxygenドキュメントを含めることができます。 新しいドキュメントブロックを始めるには、 要約説明は、 doxygenのコメントブロック内部では、通常のdoxygenマーキングならすべてサポートされます。例外は、次の2つの段落で述べます。 doxygen コメントブロックが doxygen コメントブロックが 名前空間、クラス、関数や変数を認識させるには、次のTclコマンドを使えます。コマンドの前の行にドキュメントブロックを配置できます。
doxygenスタイルのコメントを使った例です。 コメントブロックの解剖前節では、コード内のコメントをdoxygenに知らしめる方法に焦点をあてました。 要約説明と詳細説明の違い、構造化コマンドの使い方を説明しました。 当節では、コメントブロックの内容に焦点をあてます。 doxygenは、さまざまなスタイルのコメント形式をサポートします。 最も単純な形式は、プレインテキストです。出力にそのまま出現し、短い説明にぴったりです。 長めの説明には、構造が必要になることが多いでしょう。例えば、逐語テキスト、リスト、単純なテーブルなど。このため、doxygenでは、Markdown 構文をサポートします。また、Markdown Extraも部分的にサポートします。 Markdownは、設計上、読み書きが非常に容易です。 そのフォーマットは、プレインテキスト・メール形式に基づいています。 Markdownは、プロジェクトの導入ページなどにふさわしい、単純で一般的なフォーマットに効果が大きいです。Doxygenでは、markdownファイルの直接読み込みをサポートします。 詳しくは、markdownを参照してください。 プログラミング言語特有のフォーマットに対応するため、doxygenは、Markdownフォーマットの上に2つの形式のマークアップを追加しました。
これでも充分でなければ、doxygenはHTMLマークアップ言語の サブセットのサポートもしています。 次 のセクションに行く / インデックス に戻る |
|
|
This page was last modified on Mon Oct 25 2021.
© 1997-2021 Dimitri van Heesch, first release 27 oct 1997.
© 2001 OKA Toshiyuki (Japanese translation). © 2006-2021 TSUJI Takahiro (Japanese translation). © 2006-2014 TAKAGI Nobuhisa (Japanese translation). |
