ドキュメントコメントの書き方

doxygen-comment.png
func.png

なんと、xmldocの文法も通じるぞ

まとめ

こっちだとVisual Studioでマウスオーバーしたときにポップアップで出てくる

/*** 
                @brief 概要を書く
        @param _tra 平行移動行列を渡す
        @param _rotation 回転行列を渡す
        @param _cquat 現在のクオータニオンを渡す 回転姿勢保存のための変数
        @param _tquat ターゲットクォータニオン
    */

アスタリスク三個ではじめるのがポイント
アスタリスク2個だと、doxygenでは認識されるけどVisualStudioのポップアップには出てこない

こういう書き方でもdoxygenで認識される

/// Brief
    /*! Descripiton
        @param _tra 平行移動行列を渡す
        @param _rotation 回転行列を渡す
        @param _cquat 現在のクオータニオンを渡す 回転姿勢保存のための変数
        @param _tquat ターゲットクォータニオン
    */
/** javadocの場合はアスタリスク2つで認識されるコメントであることを示す。
Eclipseで青いコメントになったらちゃんと認識されたってこと。
@param アットマークからはじめるやつで書く
*/

Doxygenの設定

Expert->Project->

で、コメント認識に関する設定項目がある。

  • JAVADOC_AUTOBRIF….JavaDoc風コメントを認識する。
  • QT_AUTOBRIF….Qtスタイル

/** Brief description (e.g.\ using only a few words). Details follow. */

基本的な原則

基本的に@マークだとなんかのパラメータになる。
公式の説明だと、円マーク\も@マークと同じような働きをするとか書いてあるけど、
Windowsだと(あるいはShift_JISで書いたコードだと?)そんなことないみたい。

BriefとDescription

Brief Descriptionはクラス一覧表に乗る説明
Descriptionはクラスのページに行った時に見れる説明のこと
Briefをヘッダにかいて、Descriptionを.cppに書くスタイルにしよっかな。

様々なBriefの書き方

/// 短い概要(Brief)
/*! Description...Moreで押したら表示されるところ
 改行したかったらアスタリスク+半角スペースにする
*/

これが一番すっきりしてると思う。
DescriptionをJavaDoc風に書く方法もあるけど、Qt風のほうが、毎回アスタリスク*を書かなくて楽だ。

1行だけのbirefを書きたい

クラスのBriefはこの書き方でいいけど、メンバ変数など、横に書きたい場合はこうする
int num;///< Brief こっちだとVisual Studioでマウスホバーしたときにポップアップで出てこないので
int num2;//!< Brief この書き方のほうがおすすめ
int num3;// Visual Studioでマウスホバーした時にポップアップさせたいだけなら//プラス半角スペースだけでok

様々なDescriptionの書き方

JavaDocスタイルは、Eclipse上で書くなら簡単だけど、Visual Studioで書くには相当面倒くさい。
Qtスタイルはそんなに面倒くさくないけど、見た目があんまり好きじゃない。
/**
 * ... text ...
 */

関数

/*!
    \param _param 引数だよ
    \return 戻り値だよ
    \sa See Alsoを書こう
*/
func.png

グルーピング機能

/*! @name グループの名前
    */
    //@{
    color<float> m_BgColor;///<  背景色:白か黒
    color<float> mFontColor;///<  文字色 背景が白の時は黒・背景が黒の時は白
    color<float> mBackGround;///< 背景の四角い板グラデーション
    unsigned char m_threshold;
    int m_ValidPtNum;///< 閾値以下だった点の数 閾値と連動する
    //@}

@name でグループの名前を書く。
@{ でグループの始まり
@} はグループの終わりを示す。
グループの入れ子はできないようだ。

その他気になるコマンド

  • code / endcode コードブロックの指定。この間のテキストはコマンドが全て無効になって,そのまま出力される。コードサンプルなんかを書く時に使う。@verbatin~@endverbatimもほぼ同じだけど,これだとリンクが張られます。
  • bug バグ情報。リストとして一覧が出るので,@dateの代りに履歴として使うという使い方もある。複数書いた場合にパラグラフ結合されないという違いがある。
  • warnning 警告書き。開発者なんかに,動作仕様からは判らない重要な注意事項なんかを記載する
  • note 覚書のような,メモなんかを記載する
  • attention 注意書き。現在の使用時なんかでの注意点を記載する
  • par 段落の開始。引数は,パラグラフタイトルになる。タイトルが無しの時はコマンドのみの改行にする。
  • see / sa 参照すべき箇所や関連するクラスなんかを記載する。文中にも使える。
  • internal これ以降コメントブロックの最後までを内部用としてマークする。doxygenのオプションによって内部用記述を出すか隠すか制御出来る。内部記述を出すか隠すかは、設定ファイルの INTERNAL_DOCS を使ってください。
  • copydoc 使用検討中。指定したリンクオブジェクトの説明をコピーする。
  • li….箇条書きにする
  • deprecated….非推奨要素に属することを示すパラグラフの始まりです。

マークダウンサポート

なんと、マークダウン形式で書くと反映されるのだ!
ただし、そうするとスタイルシートいじりたくなるね。codeの部分がハイライトされてないのよ。

サポートサイト Wikidot.com