Doxygen 書き方メモ (C, C++)

C, C ++ での書き方

特殊なコメントとして記述する。以下の様なコメントは doxygen の対象となる。このどれを使ってもいいし、混ぜても問題ない。
コーディング規約との相性のいいものが良い。

/**
 * ここにテキストを書く
 */

/*!
 * ここにテキストを書く
 */

///
/// ここにテキストを書く
///

//!
//! ここにテキストを書く
//!

ファイルへのコメント

ファイルの先頭に書く

/**
 * @file ファイル名.h
 * @brief 簡単な説明
 * @author 書いた人
 * @date 日付（開始日？）
 */

関数へのコメント

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

変数へのコメント

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

マクロへのコメント

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

列挙体へのコメント

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

    //! 列挙体の各要素へのコメント
    EnumItem2 = 0x01
};

注意

• マクロに対するコメントはファイルに対するコメントが書かれていないと表に出てこない？
• namespace 内にあるコメントは namespace に対するコメントが無いと出てこない？

ヘッダファイル vs ソースファイル

これらのコメントを、関数のようなヘッダとソースファイル両方にあるものはどちらに記入すべきか？
実コードとの距離を考えて、ソースに書いたほうがいいのかなぁ？