ファイルコメント

doxygen-file.png

ファイルの先頭に書きます。ファイルコメントだけ意図的に整形がちょっと違います。

/*! @file  ファイル名。そのままファイル名。実はファイル名は書かなくても良いんですが、識別子と違ってファイル名は書かないとファイル内には現れないので、書きましょう。
    @brief 要約説明。一覧で表示され、詳細の見出しになるので、名詞が良いです。「XXXクラスヘッダ」とか「XXクラス実装ファイル」とか簡潔に。
 
    ファイルについて詳しいコメントがあれば書いてください。
    前後には空行が必要です。@briefも只のパラグラフなので、複数行書けるからです。
    @descriptionというコマンドもがありますが、簡潔に空行とします。
    ソース整形上改行を入れて折り返しても良いですけど、途中に空行が入ると終了してしまいます。
    '\n'とか'<BR>'で強制改行できますが、文章上の意味のない改行は止めましょう。代りに次のようなコマンドを使いましょう。
    @par ここに何か書くとパラグラフにタイトルが付きます。無ければ省略すればいいです。
         ここはパラグラフ本文です。インデントは必須ではありません。
    @par
   タイトル無しならこれでいいかも。
    - で箇条書きが出来ます。
    - ネストできます。
        - インデント数を認識しているので、タブ幅4でインデントしてください。
        - リスト終了はインデントを揃えて.のみの行を書きます↓
        .
    - 空行だと詳細説明セクションが終了します。
 
    @attention や
    @note や
    @sa があればここに書きます。
 
    @author 作成者の名前を書きます。書かなくても良いです。@dateのところにパッチ作成者名を書くかも知れないし、パッチの作成者として判るので。
    @date No.68881 オレオレ 変更内容。
          変更履歴を書きます。日付の代りにパッチ番号を使用します。
          - 変更内容が何も書かれていなければ新規作成した、ということです。でも、XX対応で追加とか書くことはあります。
          - パッチ番号は無ければ統合時に入れます。プレースホルダとしてメール投げて番号取ってから自分で入れるという手もあり。リポジトリならメールを投げてからコミットできますし。
          - 日付や変更者名は義務ではないです。パッチから判ることですし。
    @date No.68882
          ファイルとしての変更履歴にクラスのメンバーの変更などをいちいち書くことはしません。それらのコメントに書けば充分でしょう。ファイル全体に関わるもの、クラス自体などファイル直下の新規作成や削除は書いた方が良いでしょう。
          履歴専用のフォーマットはされないです。おまけに@dateは複数有る場合は一つのパラグラフに結合されますので、桁揃えなどは自分でやりましょう。例えばこんな感じです。
 */

サポートサイト Wikidot.com