Doxygen でどのコメントスタイルを使うべきかの考察

更新: 2006-08-08 / 作成: 2006-08-08

Doxygen のドキュメンテーションコメントを記述するときは、Javadoc スタイル、C# スタイル、Qt スタイルなど、いろいろなスタイルで記述することができます。ここでは、それぞれの記述スタイルの特徴をまとめておきます。

方法(1) Javadoc スタイル

これが一番よく使われている記法だと思います。特にこだわりがないのであれば、この記法を使っておくのが無難です。

/**
 * @brief Brief description.
 *
 * Detail description.
 * @param a  hogehoge
 * @param b  hogehoge
 */
void Hoge(int a, int b);

特徴
- brief コマンドの後ろに空行が必要なため、行数が増えてしまうし、少しアンバランスな感じになる。
- ひとつのコメントブロックとして判別しやすい。
- 簡易説明は 2 行以上に渡って記述できる（その代わり、brief の下に空行が必要という制約がある）。
- 簡易説明だけでよい場合にすっきり書くのが難しい（その場合は /// で一行で済ませる手がある）。

一行の Brief description だけ記述したい場合でも、以下のように @brief が必要です。

/**
 * @brief Brief description.
 */
void Hoge();

あるいは、

/** @brief Brief description. */
void Hoge();

通常は Javadoc スタイルで書いておいて、一行の Brief description だけを記述したい場合だけ、C# スタイルのコメントを使うのがすっきりするかもしれません。

/// Brief description.
void Hoge();

Javadoc スタイルのコメントは、以下のような file スペシャルコマンドの書き方と統一しやすいのも利点です。

/**
 * @file $File$
 * @brief Brief description.
 *
 * Detail description.
 */

/// @brief Brief description.
///
/// Detail description.
/// @param a  hogehoge
/// @param b  hogehoge
void Hoge(int a, int b);

特徴:
- 記号は 2 種類だけでよい。
- brief コマンドの後ろに空行が必要なため、行数が増えてしまうし、少しアンバランスな感じになる。
- 簡易説明は 2 行以上に渡って記述できる。

一行要約に //! を使うことができます。

//! Brief description.
/*!
 * Detail description.
 * \param a  hogehoge
 * \param b  hogehoge
 */
void Hoge(int a, int b);

Brief description にだけ Qt 風の記法を使う方法です。

//! Brief description.
/// Detail description.
/// @param a  hogehoge
/// @param b  hogehoge
void Hoge(int a, int b);

特徴
- brief コマンドのあとに、空行を入れなくてもよい。
- 行数は最も少ないが、詰め込みすぎな感じもする。
- C++ のコメントスタイルを使っているので、C 言語のコメントでまとめてコメントアウトできる（/* と */ で囲める）。

コンパクトに書けますが、ちょっとやりすぎかな。。パッと見、抵抗を感じます。

/// Brief description.
/**
 * Detail description.
 * @param a  hogehoge
 * @param b  hogehoge
 */
void Hoge(int a, int b);

簡易説明だけでよい場合に、以下のように C# スタイルで一行で記述するのであれば、このハイブリッド記法はまぁまぁイケてるかもしれません。

/// Brief description.
void Hoge();