このページの最新版は以下の場所をご覧くださいhttp://sakura-editor.wiki.sourceforge.net/DoxygenComment
ソースコード中のコメントをdoxygenの 解説に反映させるためのコメントの書き方です。新規にコメントを入れる場合は以下のルールにできるだけ従うようにしてください。
関数内のコメントはこのルールに従っていただいても意味がありません ので通常のコメントで結構です。ドキュメント生成に関係するのは、
です。
doxygenではQtスタイル及びJavaDocスタイルのコメン トを認識します．コメントには要約説明（クラス一覧やクラスメンバーのサマリー部にも表示されるもの）と詳細説明（各関数の説明部のみに出力されるもの） の二種類があります．
ブロックコメント中に1行コメントを記述するには @brief 記述子を明示的に使う必要があります．以下のようにも書くことができますが，サクラエディタのソースではあまり用いられていません．(非推奨という意味で はありません)/*! @brief 要約説明
詳細説明
*/
//! 要約説明
/*
詳細説明
*/
/** 要約説明
*
* 詳細説明
*/
1行目が要約説明として扱われます(JAVADOC_AUTOBRIEFを有効にしている場合)．
基本的には宣言文や定義文の直前に書かれたものがそのコメントと認識 されます。変数宣言などで宣言文の後ろにコメントを書きたいときにはコメントの先頭に < を入れて直前に対するコメントであることを示す必要があります。
//! 大事な変数
int nImpotant;
は
int nImportant; //!< 大事な変数
とも書けます。
関数のコメントは宣言部の直前と、実装部の直前に書くことができます．両方に書いた場合は 宣言部のものが優先されます．
コメント中ではいくつかのコマンドが使えます。詳細はマニュアルを参 照してください。
コマンドは必ず小文字で書いてください。大文字が混ざるとコマ ンドと認識されません。
doxygenはコメント中にクラス名や関数名が現れるとそれらに Hyperlinkを設定します。
ファイルのコメントは @file コマンドによって生成されます。ファイルの先頭に記述してください。
/*! @file
@brief XXXをYYYする関数群
このファイルはXXXです。
@author 作者
@date 作成日, 履歴など
*/
ここに記述した要約説明がファイル一覧につきますので，できる だけ@brief コマンドで要約説明を入れるようにしてください．
2006.04.09 Subversionへの移行に伴い，Rev. 960にてファイル冒頭にあった$Id: $，$Revision: $等の埋め込みキーワードは削除しました．これはSubversionがリポジトリ単位にバージョン番号を付与するためにファイル個別の値を記載すること にあまり意味がないことと，埋め込みキーワード部分がマージで衝突する可能性があるとの指摘を受けたことによります．
クラスに対するコメントはクラス宣言の直前に書きます。
@class コマンドを用いるとそれ以外の場所に書くことも可能ですが、特に理由がない限り直前に書くようにしてください。
ここに記述した要約説明がクラス一覧につきますので，できるだ け@brief コマンドで要約説明を入れるようにしてください．
関数の説明には引数の説明、戻り値の意味を以下のように記述します。
2005.03.31 doxygen 1.3.7より利用可能となった@paramの属性を使うようにしました．なるべく新形式を推奨します．
/*!
@brief ファイルを開いてファイルポインタを返す。
@param[in] filename ファイル名
@param[in] mode 読み出しモード
@return 成功したときはファイルポインタを返す。
失敗したときはNULLを返す。
*/
FILE* fileopen( char* filename, int mode )
パラメータの説明先頭の[in] はそのパラメータが呼び出し側から関数にパラメータを渡す目的で使われることを意味します。その反対の [out] は呼び出す側が領域だけ渡すと関数が中身をセットしてくれるような引数を表します。両方の目的に使われる引数には [in,out] と記述してください。
複数の戻り値を列挙するときは@returnの 代わりに
@retval 値 解説
という書式を使うこともできます。この場合は取りうる値の数だけ @retval を繰り返してください。また、 @returnと @retvalを併用すると“戻り値”というパラグラフが2つできてしまいます。
以下のように引数のコメントを引数の位置にも書けます。(あまり使われていません)
/*!
@brief ファイルを開いてファイルポインタを返す。
@return 成功したときはファイルポインタを返す。
失敗したときはNULLを返す。
*/
FILE* fileopen(
char* filename, //!< [in] ファイル名
int mode //!< [in] 読み出しモード
)
2005.03.31 @paramの属性がこの記法では使えないため，in,outの記述が引数の説明の所に入ります．この記法を@paramと併用する場合には整形時の出力 をそろえるために
@param argument [in] 引数説明
という従来の記法を使って
ください．(関数単位でそろえる)
コマンドから別のコマンドか空行が現れるまでが引数・戻り値の解説と 見なされてます。
以下のようにC++の文法上は正しいのにdoxygenがうまく対応 を認識できないケースがありますので，極力doxygenがわかる形で記述するようにお願いします．
クラス・構造体へのポインタ・参照を定義前あるいはinclude無 しで使う場合に
class ABC;の代わりに
class CDE {
func( ABC* p );
}
class CDE {
func( class ABC* p );
}
と記述できますが，実体を宣言する方にもclassが
付いていないとdoxygenは両者を同一と認識できません．
このコメントだけを見てその関数の動作が100%把握できるようなコ メント書くように心がけてください．そのためには
ということを具体的に記述することが必要です．また，エラーの場合の 振る舞いやも記述しましょう．
@return 大文字かどうか
では大文字の時にtrueなのかfalseなのかが曖昧ですので
@retval true 大文字
@retval false 小文字
と書いてください．
仮想関数をオーバーライドする場合，派生元と派生先で仮引数の名前が 異なっていると警告が出ます．
クラスのメンバー変数やグローバル変数のコメントは直前または直後に 書きます。
//! ファイルポインタ
FILE *fp;
int count; //!< 何かの数