つくばチャレンジ2010: Doxygen用コメントの書き方

今年は院生４名、学部生２名とつくばチャレンジ班が増員したので、Doxygenでソースコードのドキュメントを作ることにしました。

DoxygenはC++のソースコードからクラス図やコラボレーション図などを自動で生成してくれ，リンクにより関数とコード間を自由に行き来できるのでソフトウェア全体を知るためにとても便利です．ODEやIrrlichtのウェブサイトでもDoxygenで生成されたドキュメントを読むことができますね．

さて，便利なDoxygenでもクラスの機能や引数の意味までは自動的に生成してくれません．人間が何らかのコメントを書いてDoxygenに教えてやる必要があります．それでは，コメントの書き方を説明します．

コメントの書き方は何通りかありますが，ここではdemura.netで使う方法を紹介します．以下の書式はQtスタイルでdoxygenのマニュアルを参考にしました．

• ファイル　（先頭に以下を書く）
  //!   このファイルの要約を１行で書く．
  /*!
  このファイルの詳細説明を書く
  ￥file    ファイル名
  ￥author   作者
  ￥date  作成日
  */
• クラス　（直前に以下を書く）
  //!   このクラスの要約を１行で書く．
  /*!
  このクラスの詳細説明を書く
  */
• 関数　（直前に以下を書く）
  //!   この関数の要約を１行で書く．
  /*!
  この関数の詳細説明を書く
  ￥param   引数1     説明
  ￥param   引数2    説明
  ￥param[in]  引数3  説明　//  [in]はその関数に引数を渡すことを明示する場合．
  ￥param[out] 引数4  説明　// [out]はその関数で引数を計算して 呼び出し側に戻すことを明示する場合
  ￥return   戻り値の説明
  */なお，
• 変数 （単位のあるものは必ず書きましょう．バグを防げます）
  • 直前に書く場合
    //!   歩行速度 [m/s]
    double   walk_speed;
  • 直後に書く場合 (<を//!の後ろに付けるだけ）
    head_yaw_angle;  //!<  頭のヨー角[rad]

詳細はDoxygenのマニュアルをご覧ください．

でむ