開発​/doxygen

あると便利なツール

• Graphviz
  Doxygenは，クラスダイアグラムを生成する機能を持っているのだが，そこでGraphvizを利用する。DoxygenとGraphvizを使えば，クラス相関図を自動的に作ってくれる。
  Doxygenをインストールする前に，これを入れておいたほうが良い。
  http://www.graphviz.org/ のDownloadにある，Stable and development Windows Install packages（Windowsの場合）を選ぶ。（現在の安定版は， graphviz-2.28.0.msi）
  ダウンロードしたファイルをクリックしてインストールする。
• HTML Help Workshop
  MS製の，Doxygenが出力するドキュメントから，WindowsのHTML HELP（.chm)に変換するツール。
  ここのMSのサイトからダウンロード出来る。これがあれば自動的にWindows Helpファイルを作成できるようになる。
  • Doxygenでchmファイルを作る時，追加する設定

    GENERATE_HTMLHELP      = YES
    CHM_FILE               = ../xxxxx.chm
    HHC_LOCATION           = "\"C:\Program Files\HTML Help Workshop\hhc.exe\""
    GENERATE_CHI           = YES
    CHM_INDEX_ENCODING     = CP932

Doxygenのインストール

Doxygenのサイトの右側にあるDownloadするところから，Windows用インストーラーをダウンロードする。（doxygen-1.8.2-setup.exe）
これもクリックしてインストールする。
PATHを通しておく必要があるので，短めのディレクトリのほうが良い。

doxygenの設定ファイル「Doxyfile」での設定

Doxygenを実行する時に，動作を設定するためのdoxyfileをそのプロジェクト・ディレクトリに用意しておく。サンプルDoxyfile: Doxyfile
設定ファイルはDoxywizardっていうGUIツールで作成できる。一度作るとほとんど変更することはないんでエディターで編集して使っている。最初はDoxywizardを使ったほうがいいと思う。実行は，スタートメニューまたはコマンドプロンプト上でdoxywizardを実行すれば，そのディレクトリに作成される。

設定はWizardタブを開いて行う。
Project

Mode

Output

Diagrams

Expertタブ

すべての設定が完了したら，Runタブを開き，Run doxygenボタンを押す。しばらく待つとドキュメント作成が完了する。

CHMファイル作成

DOXYFILE_ENCODING      = UTF-8                   # SJISの場合は，CP932にする
PROJECT_NAME           = "XXXXXX PCB Firmware"   # 適当に
PROJECT_NUMBER         = 1.1.0                   # 適当に
OUTPUT_LANGUAGE        = Japanese                # やっぱり日本語で
HAVE_DOT               = YES                     # Graphvizで図を入れる
OUTPUT_DIRECTORY       =                         # 出力ディレクトリ（デフォルトはHTML）
TAB_SIZE               = 8                       # TAB幅
FILE_PATTERNS          = *.cpp *.c *.h           # 対象ファイルを指定
EXTRACT_PRIVATE        = YES                     # privateメンバも出力するとき

その他，いっぱいオプションがある。doxygen -gとするとコメント付きのDoxyfileを作成するんでそれを見て設定する。

2種のコメント

doxygenコメントには，「概要記述」と「詳細記述」の2つのコメントがあります。それぞれの違いは以下のとおり。

どちらもファイルの先頭，対象となる関数，構造体，C++のクラス，メンバ変数，メソッドなどの宣言や定義の前に記述する。

図は，doxygenが出力するファイルのコメントの例です。doxygenが出力するドキュメントは，「サマリー」と「詳細説明」に分かれる。サマリーには，概要記述で記載した内容が，詳細説明には概要記述と詳細記述で記載した内容が反映されるみたい。サマリーにも反映させたい内容については，概要記述に書くようにする。

書き方

• サマリーの書き方
  

  /// サマリーだよ

  とか，

  //! サマリーだよ

  注意：サマリーを複数行に書いてしまうと，詳細説明になってしまう。
• 詳細説明の書き方 QTスタイル

  /*
   * 詳細記述
   * 詳細記述
  */
  
   /*
    詳細記述
    詳細記述
   */

  JavaDocスタイル
  

  /**
   * 詳細記述
   * 詳細記述
   */
  
  /** 詳細記述 */

• 詳細説明の中でサマリーを記述しちゃう方法
  詳細説明中にサマリーを書きたい場合は，「@brief」というセクションコマンドを利用して記述する。
  @briefを利用すると，空のコメント行までがサマリーとして扱われる。
  

  /*!
   * 詳細説明
   * @brief     サマリー説明
   *             概要説明
   *
   * 詳細説明
  */
  
  /*!
  @brief	文字列の文字数を返す
  
  @param [in] s 文字列
  @return 文字数
  */
  
  /*!
  @brief	文字列での文字の位置を返す
   
  @param [in] s 文字列
  @retval 0  見つからなかった
  @retval 0以外 文字の位置
  */

• 補足説明を付けたい変数や関数の定義前に通常コメントを書く
  補足説明を付けたい変数や関数の定義前に通常コメントを書きますが，enum型や変数などの場合は定義の後にコメントを付けるケースもある。 doxygenのコメントは，このような後方コメントにも対応しており，以下のように記述することで前の宣言を修飾出来る。

  変数定義  /*!< 詳細説明 */

  とか

  変数定義  /*!< 詳細説明 */

  や，

  変数定義  ///< サマリーだよ
  int globBase = 10;  ///< 足し算用のパラメータ 

  とか

  変数定義  //!< サマリーだよ

  とかにします。

文章の飾り付けとセクションコマンド

コメントの中では"スペシャルコマンド"や"HTMLコマンド"と呼ぶ書き方で細かな指定が可能。第す。代表的なものを以下に上げてみる。

• @および\で始まる語は，doxygenコマンドとして解釈しようとする。コマンドにしない場合は，'\n'や'\0'の様にquoteする。
  <>&#%もHTMLで特殊な意味を持ちますので，エスケープする必要がある。コマンドや特殊文字を含む文を書く場合には，特殊文字を解釈しないブロックを作るコマンドがある。
• 空白行は，ブロック終了コマンドの無いブロックを終了させるという意味がある。
• コメントされている識別子を文中に書くと，自動でリンクが張られる。
• コマンドには引数がある場合がある。コマンドの後ろに何か記述している場合と，コマンドだけの行は出力結果が違うことがある。
• HTMLタグを使用すると出力に反映されるけど，プログラムのソースとしては見づらくなるから，なるべく使わないようにする。
• 単に改行しても出力されないので，ソース上の整形で単に改行するのは問題ない。

• PHPだとこんな感じ
  

  /**
   * @brief  etcクラスはその他のデータを表します。
   *
   * @author yuji
   * @see    labeledETC
   * @date   2007/04/09
   */
  class etc{
  
    /**
     * その他のデータを表す
     * @note       private String name
     * @deprecated この値を直接操作することは推奨されません。
     */
    var $name;
  
    /**
     * 名前を設定
     * @param      name 名前を指定
     * @note       void setName(String name)
     */
    function setName($name){
      $this->name = $name;
    }
  
    /**
     * 名前の取得
     * @return     String
     * @note       String getName()
     */
    function getName(){
      return $this->name;
    }
  }