[ C++で開発 ]

Doxygenコメント規約例

Doxygenは、非常に豊富なコメント書式を持っていますが、これらをすべて把握して適切なコメントを書くことは苦痛です。そこで、あらかじめ特定のコメント規約セットとそのDoxygen設定ファイルを定義し、これを雛形として使うのがよいかと思います。

コメント規約セット（その１） Java風味

JavaDocで慣れた人向けのC++用Doxygenコメント規約例を定義します。

Doxygen設定項目

設定項目	設定値	備考
PROJECT_NAME	センサ収集プロジェクト	プロジェクト名またはプログラム名を記述する
PROJECT_NUMBER	1.1	バージョン情報を記述する。バージョン管理下のプロジェクトではリリースブランチ名がよい
OUTPUT_DIRECTORY	doc/api	カレントディレクトリ下のdoc/apiにドキュメントを生成する
OUTPUT_LANGUAGE	Japanese	日本語出力する
TAB_SIZE	4	デフォルトは8桁だが、大体のコードのインデントは4桁なので
HAVE_DOT	YES	graphvizを使用する
RECURSIVE	YES	doxygen実行ディレクトリ以下を再帰的に探してドキュメントを生成する
JAVADOC_AUTOBRIEF	YES	ピリオドまでのコメント、または空コメント行までの最初のコメントを要約説明として扱う
UML_LOOK	YES	クラス図をUML形式にする
GENERATE_LATEX	NO	LaTeX出力をしない（時間がかかるので、通常は抑制し、必要時にYESにする）

コメント規約セット

ファイル・コメント

ファイルの先頭にコメントします。

T.B.D.

クラス・コメント

クラス定義の直前にコメントします。

クラスコメント規約
/** * 各具象センサを一括して扱うための抽象基底クラス * * 型として扱えることを目的とし、属性・操作は定義していない。 * @author torutk * @version 1.0 */ class Sensor { public: Sensor(); virtual ~Sensor(); };

クラスコメント規約

/**
 * 各具象センサを一括して扱うための抽象基底クラス
 *
 * 型として扱えることを目的とし、属性・操作は定義していない。
 * @author torutk
 * @version 1.0
 */
class Sensor {
public:
    Sensor();
    virtual ~Sensor();
};

　コメントの一行目は、要約説明となります。空コメント行を入れると、それ以降が詳細説明となります。空コメント行がなくても、ピリオド('.')で区切れば要約説明と詳細説明を分離できますが、日本語コメントを記述していると、読点にしてしまいがちで要約説明の完了とならないため、規約としては1行空コメントを入れることにします。

メンバ関数コメント

ヘッダーファイルのメンバ関数宣言の直前にコメントします。

メンバ関数コメント規約
class PassiveSonar : public Sonar { ... /** * 計測周期を設定する * * 計測を行う周期を引数で指定した値に設定する。 * @param[in] interval 計測周期(ms) * @retval true 指定した周期に設定された * @retval false 周期は設定されない * @throw std::out_of_range 引数の指定周期がセンサの計測可能範囲外 * @attention 計測周期の範囲は、intervalspecで定義される */ boolean setInterval(int interval); ... };

メンバ関数コメント規約

class PassiveSonar : public Sonar {
    ...
    /**
     * 計測周期を設定する
     * 
     * 計測を行う周期を引数で指定した値に設定する。
     * @param[in] interval 計測周期(ms)
     * @retval true 指定した周期に設定された
     * @retval false 周期は設定されない
     * @throw std::out_of_range 引数の指定周期がセンサの計測可能範囲外
     * @attention 計測周期の範囲は、intervalspecで定義される
     */
    boolean setInterval(int interval);
    ...
};

　コメントの1行目は、要約説明となります（クラスコメント同様）

　メンバ関数定義（ソースファイル）にもコメントを書くと、ヘッダーのコメントと入り混じってしまいます。通常ヘッダーの方にコメントを記載します。ただし、実装上の制約や既知の問題など、関数仕様ではなく実装の問題についてのコメントは、ソース側に記述します。そのときは、@note（覚え書き）、@bug（バグ）、@warning（警告）のいずれかを使用し、実装特有の問題について記述します。　

　引数の説明は、@param[in|out|in,out]を使用します。

　戻り値の説明は、@return または @retval が利用できます。@return は一つの関数の説明に１つしか使用できないので、戻り値の値を複数列挙して説明するときは、@retvalを使います。

　@return を使用する例。

/**
 * 現在使用されている計測周期を取得する
 *
 * 現在センサが使用している計測周期の値を取得する。
 * @return 計測周期(ms)
 */
int getInterval() const;

　@attentionは、仕様上の注意点を記述します。

コメント共通ルール

箇条書き

インデントをそろえたハイフン('-')で箇条書きになります。

箇条書きコメント規約
class PassiveSonar : public Sonar { ... /** * センサ設置仰角を船首軸を水平面とした相対角度で取得する * * 船首軸は航行時に変動するため、以下の条件での取得とする。 * - センサ計測周期の開始時点でセンササブシステムが保持している船首軸を使用 * - 計測周期が間引きモードの場合は計測不能 * - 間引きモードのときに本関数が返す値は不定値とする * - 間引きモードか否かの検査は行わない * * @return 相対仰角 */ double getRelativeAngle(); ... };

箇条書きコメント規約

class PassiveSonar : public Sonar {
    ...
    /**
     * センサ設置仰角を船首軸を水平面とした相対角度で取得する
     * 
     * 船首軸は航行時に変動するため、以下の条件での取得とする。
     * - センサ計測周期の開始時点でセンササブシステムが保持している船首軸を使用
     * - 計測周期が間引きモードの場合は計測不能
     *     - 間引きモードのときに本関数が返す値は不定値とする
     *     - 間引きモードか否かの検査は行わない
     *
     * @return 相対仰角
     */
    double getRelativeAngle();
    ...
};

箇条書きブロックの最後に空コメント行を設けます。
箇条書きのインデントは可能です。