/*! @file  ファイル名。そのままファイル名。実はファイル名は書かなくても良いんですが、識別子と違ってファイル名は書かないとファイル内には現れないので、書きましょう。
    @brief 要約説明。一覧で表示され、詳細の見出しになるので、名詞が良いです。「XXXクラスヘッダ」とか「XXクラス実装ファイル」とか簡潔に。

    ファイルについて詳しいコメントがあれば書いてください。
    前後には空行が必要です。@briefも只のパラグラフなので、複数行書けるからです。
    @descriptionというコマンドもがありますが、簡潔に空行とします。
    ソース整形上改行を入れて折り返しても良いですけど、途中に空行が入ると終了してしまいます。
    '\n'とか'<BR>'で強制改行できますが、文章上の意味のない改行は止めましょう。代りに次のようなコマンドを使いましょう。
    @par ここに何か書くとパラグラフにタイトルが付きます。無ければ省略すればいいです。
         ここはパラグラフ本文です。インデントは必須ではありません。
    @par
   タイトル無しならこれでいいかも。
    - で箇条書きが出来ます。
    - ネストできます。
        - インデント数を認識しているので、タブ幅4でインデントしてください。
        - リスト終了はインデントを揃えて.のみの行を書きます↓
        .
    - 空行だと詳細説明セクションが終了します。

    @attention や
    @note や
    @sa があればここに書きます。

    @author 作成者の名前を書きます。書かなくても良いです。@dateのところにパッチ作成者名を書くかも知れないし、パッチの作成者として判るので。
    @date No.68881 オレオレ 変更内容。
          変更履歴を書きます。日付の代りにパッチ番号を使用します。
          - 変更内容が何も書かれていなければ新規作成した、ということです。でも、XX対応で追加とか書くことはあります。
          - パッチ番号は無ければ統合時に入れます。プレースホルダとしてメール投げて番号取ってから自分で入れるという手もあり。リポジトリならメールを投げてからコミットできますし。
          - 日付や変更者名は義務ではないです。パッチから判ることですし。
    @date No.68882
          ファイルとしての変更履歴にクラスのメンバーの変更などをいちいち書くことはしません。それらのコメントに書けば充分でしょう。ファイル全体に関わるもの、クラス自体などファイル直下の新規作成や削除は書いた方が良いでしょう。
          履歴専用のフォーマットはされないです。おまけに@dateは複数有る場合は一つのパラグラフに結合されますので、桁揃えなどは自分でやりましょう。例えばこんな感じです。
 */

/*!
 @brief 説明要約。ファイルコメント参照。

        関数の詳しい説明。ファイルコメント参照。

 @attention 概要参照。
 @note 概要参照。
 @sa 概要参照。関連する型の定義や、関数など。

 @param [in]     仮引数名      引数の説明。\n
                               @paramは引数を採り、フォーマットされるので、引数名と説明を : で区切ったりしてはいけません。
                               ソース上の整形として、改行・空白（半角スペースとタブ）文字による桁揃えはして構いません。でも、あんまり長いようなら、関数の詳細説明に書いた方が良い内容かもしれません。
 @param [out]    仮引数名2     引数の型名を書く必要はありません。これが表示される位置には関数の宣言もあるからです。
        改行したときにあまり深くインデントしなくても良いです。しかし、この例のようにばらばらではなく、少なくとも一つの関数ブロックでは統一しましょう。
 @param [in,out] 仮引数名その3 引数のタイプは[in][out][in,out]です。ポインタ及び参照の引数を内部で変更している場合は、その変更が呼び出し側から無意味であっても、outも付けるべきです。
 @param [in]     仮引数名４    引数の値の範囲が限られている場合は@argで列挙します。数が多い場合は値の定義を@saで参照させればよいでしょう。
                 @arg 引数の取り得る値1 : その説明1。@argは実際にはただのリストなので空白文字でで勝手に桁揃えされたりはしません。
                 @arg 引数の値2         : その説明2。桁を揃えたければスペースを挿入してください。

 @return 戻り値の説明。無いときはなるべく「なし」と書くべきです。BOOL値やエラーコードなど値が何種類か決まっている場合には以下のように続けて@retvalで列挙します。
         引数と同じく型は必要有りませんが、型がPODでないときにオブジェクト自体（値、一時コピー）を返すのか、参照（ポインタ）を返すのかを注意を喚起する意味で書いた方が良いと思います。
 @retval 戻り値の例 とその意味。種類の数だけ列挙します。
 @retval 戻り値の例その2 @retvalは値とその意味を空白文字で区切ると、桁揃えされます。空白文字は複数連続しても良いのでソースコメント上で揃えたい場合はご自由に。
 @retval その他       システムのエラーコード。数が多い場合にはこの様に、主な物と「その他」で良いです。

 @author ファイルコメント参照。
 @date ファイルコメント参照。
 */

/*!
 @brief ファイルコメント参照。

        ファイルコメント参照。

 @attention 概要参照。
 @note 概要参照。
 @sa 概要参照。参照すべき関連項目があれば書きます。

 @author ファイルコメント参照。
 @date ファイルコメント参照。
 */
class foo : public bar
{
    inline void func();   // 宣言だけなのでdoxygenコメントにしないこと
    //! 書いても良いけど、実装部分の@briefの内容に合わせること。
    void func2();

    int 変数宣言1;   //!< この変数の説明は一行だけ @date パッチ番号 @date パッチ番号 変更履歴もちゃんと書けます。
    int 変数宣言2;   /*!< この変数の説明は複数行書きたいとき、
                          こんな感じで複数行書けます。 @date パッチ番号 */

    /*! 前に書くことも出来ます。
        @date パッチ番号    */
    int 変数宣言;

    /*! 列挙型も各メンバーに説明が書けますよ。
        @date パッチ番号    */
    enum foo_values
    {
        EFooFirstVal,  //!< こうやって、各メンバの説明を書けます。
        EFooLastVal    //!< こうやって、各メンバの説明を書けます。
    }

    /*!
     @brief 列挙型や変数の詳細なコメント

            列挙型や変数でも必要ならばクラスなどと同じように詳しく書いても良いのですよ。

     @attention 概要参照。
     @note 概要参照。
     @sa 概要参照。
     @date パッチ番号
     */
    enum foo_values
    {
        EFooFirstVal,   //!< こうやって、各メンバの説明を書けます。
        EFooLastVal     //!< こうやって、各メンバの説明を書けます。
    };
};

/*!
 @brief インライン関数

        定義がある場合はヘッダーファイル内でもコメントを書きます。詳細は関数コメント参照。
 */
inline void foo::func()
{
    // ちょっと複雑なインライン関数の実装は
    // クラス定義内からは追い出した方が簡潔
    // になる。
    // でも使用箇所と翻訳単位が同じである必
    // 要があるからクラス定義の後ろ、ヘッダ
    // ファイルの末尾に書く。.inlファイルに
    // 別けて、ヘッダファイルで#includeする
    // という手もあり。
}