QBOQにおけるコメントの書き方を扱います

QBOQメインページに戻る
QBOQコーディングルール

ドキュメント生成に使うソフトはdoxygenです

ドキュメント生成にはdoxygenを使用します。ですので、QBOQではdoxygenが認識できる用にコメントを書きます。以下にあげる要素に対するコメントはできる限りこのコメントルールに基づいて記述します。関数やメソッド内のコメントはここに書かれている形式で記述しても意味がありません。(なおQBOQではできる限りQtライクなコーディングを行いますので、#defineによる定数宣言やマクロではなく、const変数、テンプレート関数を使用します。グローバル変数もできるだけ使用しません。)

ファイル	ファイルの先頭に書く
クラス	クラス宣言の直前に書く
メソッド	メソッド実装の直前に書く
メンバ変数	宣言直後に書く
グローバル変数	宣言の直前
関数	関数の実装の直前に書く
定数宣言	enumなどで宣言される定数群の直後

変数や定数は直後、それ以外は直前。実装と宣言が別々の場合は実装の方に書く。

ファイルのコメントの書き方

/*!@file
@brief 簡単な説明

一行あけて、詳細な説明
@author 作者
@date 作成日, 履歴など*/

クラスのコメントの書き方

/*!@brief 簡単な説明

クラスの説明*/

メソッド、関数のコメントの書き方

/*!メソッド、関数の説明

@param[in] p0 入力用引数の説明
@param[out] p1 出力用引数の説明
@param[in,out] p2 入出力用引数の説明
@return 戻り値の説明。
戻り値の説明二行目。*/

もしくは

/*!メソッド、関数の説明

@param[in] p0 入力用引数の説明
@param[out] p1 出力用引数の説明
@param[in,out] p2 入出力用引数の説明
@retval 値 戻り値の説明。
@retval 値 戻り値の説明。*/

以下の項目を書くようにします。

• 使用条件
• 引数の説明、確保の仕方など
• 戻り値の説明
• エラー時の挙動

メンバ変数、グローバル変数、定数のコメントの書き方

int var; //!< 説明