DoxygenComment

開発に参加したい方へ＞doxygen＞コメントの書き方

コメントの書き方(クラス・関数のコメント)

ソースコード中のコメントをdoxygenの解説に反映させるためのコメントの書き方です。新規にコメントを入れる場合は以下のルールにできるだけ従うようにしてください。

関数内のコメントはこのルールに従っていただいても意味がありませんので通常のコメントで結構です。ドキュメント生成に関係するのは、

• ファイル
• クラス
• メンバー関数（Inline含む）
• メンバー変数
• グローバル変数
• クラスのメンバーでない関数
• 定数宣言 (#define, enum)
  です。

doxygenで認識されるコメント

スタイル

doxygenではQtスタイル及びJavaDocスタイルのコメントを認識します．コメントには要約説明（クラス一覧やクラスメンバーのサマリー部にも表示されるもの）と詳細説明（各関数の説明部のみに出力されるもの）の二種類があります．

Qtスタイル

/*! @brief 要約説明
 詳細説明
*/

ブロックコメント中に1行コメントを記述するには @brief 記述子を明示的に使う必要があります．以下のようにも書くことができますが，サクラエディタのソースではあまり用いられていません．(非推奨という意味ではありません)

//! 要約説明
/*
 詳細説明
*/

JavaDocスタイル

/** 要約説明
 *
 * 詳細説明
 */

1行目が要約説明として扱われます(JAVADOC_AUTOBRIEFを有効にしている場合)．

コメントの位置

基本的には宣言文や定義文の直前に書かれたものがそのコメントと認識されます。変数宣言などで宣言文の後ろにコメントを書きたいときにはコメントの先頭に < を入れて直前に対するコメントであることを示す必要があります。

//! 大事な変数
int nImpotant;

は、次のようにも書けます。

int nImportant; //!< 大事な変数

関数のコメントは宣言部の直前と、実装部の直前に書くことができます．両方に書いた場合は宣言部のものが優先されます．

Doxygenへの指示

コマンド

コメント中ではいくつかのコマンドが使えます。詳細はマニュアルを参照してください。

コマンドは必ず小文字で書いてください。大文字が混ざるとコマンドと認識されません。

自動的なリンクの作成

doxygenはコメント中にクラス名や関数名が現れるとそれらに Hyperlinkを設定します。

具体的なコメントの書き方

ファイル

ファイルのコメントは @file コマンドによって生成されます。ファイルの先頭に記述してください。

/*! @file
 @brief XXXをYYYする関数群
 このファイルはXXXです。
 @author 作者
 @date 作成日(xxxx.xx.xx), 履歴など
*/

ここに記述した要約説明がファイル一覧につきますので，できるだけ@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がわかる形で記述するようにお願いします．

struct/classの有無

クラス・構造体へのポインタ・参照を定義前あるいはinclude無しで使う場合に

class ABC;
class CDE {
 func( ABC* p );
}

の代わりに

class CDE {
 func( class ABC* p );
}

と記述できますが，実体を宣言する方にもclassが付いていないとdoxygenは両者を同一と認識できません．

---

このコメントだけを見てその関数の動作が100%把握できるようなコメント書くように心がけてください．そのためには

• どういうとき
• 何を与えると
• 何が返ってくる
  ということを具体的に記述することが必要です．また，エラーの場合の振る舞いやも記述しましょう．

[例1]

@return 大文字かどうか

では大文字の時にtrueなのかfalseなのかが曖昧ですので

@retval true 大文字

@retval false 小文字

と書いてください．

継承時の変数名

仮想関数をオーバーライドする場合，派生元と派生先で仮引数の名前が異なっていると警告が出ます．

変数

クラスのメンバー変数やグローバル変数のコメントは直前または直後に書きます。

//! ファイルポインタ
FILE *fp;
int count; //!< 何かの数

---