背景
仕事でプログラミングする際に、関数に説明を追加する場合が多いため、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対応のコメント記載方法を調査、記載した
参考文献
変更履歴
- 2019/09/01: 新規作成
