その３ ヘッダーファイルにDoxygenコメントを追加する
Doxygenはコードにある特殊なコメントを解読してマニュアルに追加していきます。このコメントを書く作業はプログラマが行いますが、それが同時にマニュアル作成になっているわけです。この章ではヘッダーファイルに書くコメントを見ていく事にしましょう。
① 各種コメント
テストとして次のようなコードにDoxygenコメントをつけて行きます：
class MyClass {
public:
MyClass();
virtual~ MyClass();
int get();
bool set( int value );
protected:
void clamp( int value );
protected:
int m_value;
};
このまっさらな段階でDoxygenを通すとこちらのようなマニュアルが作成されます。見るべきは[クラス]タブ内の[構成]タブです。ここにDoxygenが対象にした全クラスが並びます。今はMyClassしかありませんのでそれをクリックして下さい。何もコメントをつけなくてもDoxygenはここまで整形したマニュアルを作成してくれます。すばらしいですね(^-^)。ソースコードにDoxygenコメントを追加していくと、この初期マニュアルに反映されていきます。
○ クラス説明
では、最初にヘッダーの先頭に、
/**
* Doxygen説明用のダミークラス。
* 最低限のメソッドが揃っています。
*/
という1行を追加します。するとマニュアルに、
という箇所が追加されます。簡単にクラスの説明文を書く事ができます。Doxygenコメントは基本的に「/**～*/」で囲みます。これはJavaDocの方式ですが、Doxygenにはこれ以外にいくつかの亜種スタイルが定義されています。自分の好きなスタイルを使うのが良いかなと思います。
○ メソッド説明
クラス内のコンストラクタの上に以下のコメントを入れます：
/**
* コンストラクタ
*/
これによりコンストラクタの中に説明文が追加されます：
同様にデストラクタの上にコメントを載せると、マニュアルのデストラクタ部分にも追加されます。
続いてgetメソッドにコメントを付けましょう。getメソッドは引数はありませんが戻り値としてint型を返します。この戻り値についての説明を書くことにします：
/**
* 値を取得する
* @return 現在の値。無効の場合は-1。
*/
するとマニュアルではこうなります：
@returnというプレフィックスを付けると、後置の文章が戻り値の説明文と扱われます。
最後にsetメソッドにコメントを付けましょう。setメソッドは戻り値と引数の両方を持っています。引数を表すプレフィックスは@paramです：
/**
* @brief 値を設定する
* @param value 現在の値
* @return 成功したらtrue。無効な値が設定された場合はfalse。
*/
説明文のプレフィックスは@briefです。パラメータを表す@paramの後に変数名を記載します。一つ以上のスペースを空けて説明文を書くと、マニュアルでは次のようになります：
綺麗に整形されます。
○ メンバ変数
メンバ変数も基本的にDoxygenコメントで説明文を書くだけです。m_value変数の上に同様のコメント分を付記します：
/** @brief 値 */
これで次のような説明文が付きます：
ただ、メンバ変数の「上部」にコメントを書くのは何となく気持ちが悪い感じもします。そこでDoxygenには簡便法が提供されています。メンバ変数の右に次のようにコメントを書く事が可能です：
/**< @brief 値 */
変数の後ろに説明文を付ける時には「/**<～*/」で挟みます。「小なり」が付いているのに注意です。またもっと簡便に、
//!< @brief 値
や、
///< @brief 値
という書き方もできます。これらは1行コメントとして扱われています。こちらの方が最後の「*/」を付けなくて良いので楽ですよね。
さて、以上のDoxygenコメントを付記したヘッダーファイルは次のようになります：
/**
* @brief
* Doxygen説明用のダミークラス
* 最低限のメソッドが揃っています。
*/
class MyClass {
public:
/**
* @brief コンストラクタ
*/
MyClass();
/**
* @brief デストラクタ
*/
virtual~ MyClass();
/**
* @brief 値を取得する
* @return 現在の値。無効の場合は-1。
*/
int get();
/**
* @brief 値を設定する
* @param value 現在の値
* @return 成功したらtrue。無効な値が設定された場合はfalse。
*/
bool set( int value );
protected:
/**
* @brief 値をクランプする
* @param value 現在の値
*/
void clamp( int value );
protected:
int m_value; //!< @brief 値
};
普段書くコメントを少し定型化した状態ですが、これでこちらにあるような綺麗なマニュアルができてしまいます。
このようにDoxygenを用いる事で、プログラム上のコメントがそのままマニュアルになってしまいます。面倒なメソッドやクラスの記載を自動化してくれるのはありがたいですね。また、これにより「コード上のコメントとマニュアルの2箇所訂正」のような危険な重複更新が無くなります。クラスの仕様が変わる度にそういう書き直していたら、いつかどこかで片方だけ訂正していなかったというヒューマンエラーが出ます。ドキュメントが嘘をつく程怖い事はありません。
そういうエラーを回避するためにもDoxygenのような自動マニュアル生成ツールを活用していきたいものです。
