Doxygen対応のコメント記載方法(C, C++)

背景

---

仕事でプログラミングする際に、関数に説明を追加する場合が多いため、Doxygen対応のコメント方法について記載する。

記事の目的

---

Doxygen対応のコメント記載方法について記す

Doxygen対応のコメント

---

ここでは、Doxygen対応のコメント記載方法について記す。

ファイルへのコメント

ファイルの先頭に、ファイル内のプログラムの説明を記載する。

/**
 * @file ファイル名.h
 * @brief 簡単な説明
 * @author 書いた人
 * @date 作成日付
 */

関数へのコメント

関数毎に、関数の説明を記載する。

/**
 * @fn func1(int, int)
 * ここに関数の説明を書く
 * @brief 要約説明
 * @param arg1 引数の説明
 * @param arg2 引数の説明
 * @return 戻り値の説明
 * @sa 参照すべき関数を書けばリンクが貼れる
 * @detail 詳細な説明
 */
void func1(int arg1, int arg2)
{}

変数へのコメント

変数毎に、変数の説明を記載する。

//! 変数へのコメント
int a = 0;

マクロへのコメント

マクロ毎に、マクロの説明を記載する。

/** @def
 * マクロのコメント
 */
#define MAX_XXX 256

列挙体へのコメント

列挙体毎に、列挙体の説明を記載する。

/**
 * @enum Enum
 * 列挙体の説明
 */
enum Enum {
    //! 列挙体の各要素の説明
    EnumItem1 = 0x00,

    //! 列挙体の各要素の説明
    EnumItem2 = 0x01
};

構造体へのコメント

構造体体毎に、構造体の説明を記載する。

/**
 * @struct     構造体名
 * @brief      構造体の説明
**/
struct Struct{
    //! 構造体の各要素の説明
    StructItem1 = 0x00,

    //! 構造体の各要素の説明
    StructItem2 = 0x01
};

クラスへのコメント

クラス毎に、クラスの説明を記載する。

int global_var1
int global_var2
int global_var3
int global_var4

/*! @class Class1
    @brief  クラスの説明
*/
class Class1 {
public:
    /*! メンバ1の説明 */
    int member1;

    int member2; /*!< メンバ2の説明を横につける */

    /*! メソッド1の説明 */
    int method1(int var1, int var2);

    /*! メソッド2の説明。詳細説明
        @param[out]     var1    var1の説明
        @param[in]      var2    var2の説明
        @param[in,out]  var3    var3の説明
        @par            Refer
        - 参照するグローバル変数 global_var1
        - 参照するグローバル変数 global_var2
        @par            Modify
        - 変更するグローバル変数 global_var3
        - 変更するグローバル変数 global_var4
        @return         成功 0, 失敗 0 以外 など
        @exception      例外。不要であればnoneを記述
    */
    int method2(int var1, int var2, int var3) {
    ...
    }
};

まとめ

---

• Doxygen対応のコメント記載方法を調査、記載した

参考文献

---

• Doxygen 向け C/C++ ファイルのコメントテンプレート
• Doxygen 書き方メモ (C, C++)
• クラス・構造体・メソッド 関連

変更履歴

---

1. 2019/09/01: 新規作成