Doxygen の使いかた
非常に便利なコード ドキュメント作成ツール、Doxygen についての覚え書き。
Doxygen とは？
Doxygen とはソースコード ドキュメンテーション ツールである。
ソフトウェア開発をしていると新参メンバーや外部ユーザー向けの API リファレンスなどを求められる機会がわりとある。そんな時にコードやコメントを自動解析してドキュメント生成してくれると便利。Doxygen はそのような要求を叶えてくれる。
この種のツールでは Java の Javadoc や.NET の NDoc、Sandcastle などが有名。これらが特定のプログラミング言語やプラットフォームに最適化されているのに対して Doxygen は総合的・網羅的である。多数の言語に対応し Windows、Mac、Linux 上で動作する。
ドキュメントの出力形式も豊富。HTML を基本とし、LaTeX、XML、CHM (HTML ヘルプ)、PDF など様々な形式をサポートしている。
これだけ多機能にもかかわらずフリーウェアである。現時点で十分に有用だが常に改善され続けている。実にありがたい。
インストール
今回は Windows 7 64bit 環境にインストールする。32bit だったり Windows XP などでも手順はそれほど変わらないはず。
Graphviz
ではさっそく Doxygen のインストール！とゆきたいところだが先に Graphviz を入れる。これは DOT というスクリプト言語によってグラフ生成するためのツール。Doxygen はクラス ダイアグラムを生成する機能を持っているのだが、そこで Graphviz を利用する。
現行の Doxygen なら大丈夫かもしれないが古いバージョンでは先に Graphviz を入れないと手動設定が必要だった。そのため Graphviz からインストールする。
Graphviz のダウンロード ページにゆくと様々なプラットフォーム用リンクがあるが今回は Windows 環境にインストールするので Stable and development Windows Install packages を選択。
ページへのアクセスが初めてなら最下段へ使用許諾のテキストと共に Agree/Disagree というリンクが表示される。内容を確認したうえで Agree を選ぶ。するとインストーラのページに移動するので graphviz-2.28.0.msi (2012/1/29 現在の最新) をクリックしてダウンロードを開始する。
セットアップについては特に迷うところもないため割愛。
Doxygen
Doxygen のインストール。
上記ダウンロードページの A 32-bit binary distribution for Windows XP/Vista/7 という欄にある doxygen-1.7.6.1-setup.exe の横にインストーラのリンクがある。プロトコルに FTP/HTML を選べる。特にこだわりがなければ HTTP でよい。
Doxygen のセットアップも、特に困るような箇所はない。
HTML Help Workshop
Doxygen で CHM (HTML ヘルプ) 形式のドキュメントを生成したい場合は HTML Help Workshop もインストールしておく。
上記ダウンロード ページにゆくと 3 種類のリンクがある。これらから htmlhelp.exe を選ぶ。HelpDocs.zip と htmlhelpj.exe はツールに関するドキュメントなので CHM 生成だけなら不要。
ダウンロードした htmlhelp.exe を実行するとセットアップが開始される。Doxygen からこのツールを利用するとき実行ファイルとなる hhc.exe のパスが必要になるためインストール先をたずねられたらパスをメモしておくとよい。
Doxygen を使ってみる
Doxygen のセットアップが完了したら Doxywizard を起動する。これは Doxygen の設定・実行用 GUI ツールである。Doxygen の設定ファイルはテキストエディタでも編集可能だが面倒だしタイプミスも怖いので、特別な理由がない限り Doxywizard を利用するのがよいと思う。
というわけで Doxywizard を使ってみよう。スタートメニューから「doxygen」→「Doxywizard」を選ぶか、コマンド プロンプト上で doxywizard とタイプしてから Enter キーを押すことでツールが起動される。
画面上の説明どおりに設定してゆく。
まずは最上段から Doxygen の作業フォルダを指定しよう。Doxygen 以外のファイルやフォルダが存在しない場所を選ぶとよい。画面中段から下が設定部分となる。タブでモードを切り替えられる。それぞれの役割は以下。
| 項目 | 内容 |
|---|---|
| Wizard | 簡易設定。ウィザード形式で Project ～ Diagrams まで設定してゆく。 |
| Expert | 高度な設定。Wizard より細かな設定をおこなえる。 |
| Run | ドキュメント生成などを実行できる |
作業用フォルダを設定したら Wizard タブを開く。左がウィザード設定ページの選択、右側は設定となる。ウィザードは Project から始まる。
Project ページ。プロジェクト全般の設定をおこなう。項目は以下。
| 項目 | 内容 |
|---|---|
| Project name | プロジェクト名。ドキュメントのタイトルなど様々な場所に反映される。 |
| Project synopsis | プロジェクト概要。出力形式が HTML の場合、タイトル直下に説明文として添えられる。 |
| Project version or id | プロジェクトのバージョン情報、または識別子。出力形式が HTML の場合、タイトル右側に添えられる。 |
| Project logo | プロジェクトのロゴとなる画像ファイル。出力形式が HTML の場合、タイトル左側に画像として挿入される。 |
| Select code directory | 解析対象とするソースコードを格納したフォルダの場所。相対パスも指定できる。 |
| Scan recursively | ソースコードのフォルダが階層化されており、それらも解析する場合はチェックする。 |
| Destination directory | ドキュメントの出力先。未指定なら作業フォルダが選ばれる。 |
ひととおり設定したら Next ボタンを押して次へ。
Mode ページ。ソースコードの解析方法に関する設定をおこなう。項目は以下。
| 項目 | 内容 |
|---|---|
| Select the desired extraction mode | 解析対象。Documented entities only はドキュメント化されたファイル ( コメントが含まれるということだろうか？ ) のみ。All Entities ならすべて。Include cross-referenced はソース間で相互参照がある場合、それらも含む。 |
| Select programming language to optimize the result for | 最適化するプログラミング言語。プロジェクトのメイン言語を選ぶ。 |
ひととおり設定したら Next ボタンを押して次へ。
Output ページ。ドキュメントの出力形式に関する設定をおこなう。設定項目は以下。
HTML
| 項目 | 内容 |
|---|---|
| plain HTML | 標準の HTML を出力する。 |
| with navigation panel | ページの左側にナビゲーション パネルを持つ HTML を出力する。 |
| prepare for compressed HTML(.chm) | Microsoft Compiled HTML Help ( CHM ) 形式で出力する。 |
| With search function | PHP の稼働している Web サーバーに配置したとき、検索機能を有効にする。 |
| Change color... | HTML 出力する際の全体的な色あいを変更できる。既定のデザインを踏襲しつつ、色のみを調整するようになっている。 |
LaTeX
| 項目 | 内容 |
|---|---|
| as intermediate format for hyperlinked PDF | LaTeX 用の中間形式としてハイパーリンク形式の PDF を出力する。 |
| as intermediate format for PDF | LaTeX 用の中間形式として単一の PDF を出力する。 |
| as intermediate format for PostScript | LaTeX 用の中間形式としてポストスクリプト ファイルを出力する。 |
その他
| 項目 | 内容 |
|---|---|
| Man pages | UNIX の man ( マニュアル ) コマンド用ファイルを出力する。 |
| Rich Text Format(RTF) | リッチテキスト形式のファイルを出力する。 |
| XML | XML 形式のファイルを出力する。独自の出力形式が欲しい場合、このファイルから変換するのがよさそう。 |
ひととおり設定したら Next ボタンを押して次へ。
Diagrams ページ。ダイアグラムの出力設定をおこなう。項目は以下。
Diagram to generate
| 項目 | 内容 |
|---|---|
| No diagrams | ダイアグラムを出力しない。 |
| Use built-in class diagram generator | Doxygen に内蔵されてるジェネレータを利用してダイアグラムを出力する。 |
| Use dot tool from the GraphViz package to generate | GraphViz を利用してダイアグラムを出力する。詳細設定は Dot graphs to generate 欄でおこなう。 |
Dot graphs to generate
| 項目 | 内容 |
|---|---|
| Class diagrams | クラス図を作成する。 |
| Collaboration diagrams | コラボレーション図を作成する。 |
| Include dependency graphs | インクルード依存グラフを作成する。 |
| Include by dependency graphs | インクルード依存グラフを作成する。INCLUDED_BY_GRAPH の説明を読むに、ヘッダの間接インクルードによって生じた依存関係も含むようだ。 |
| Call graphs | 呼び出しグラフを作成する。これをチェックすると関数やメソッドの呼び出し解析が実行されるので、ドキュメント生成の時間がとても長くなる。 |
| Called by graphs | 間接的な呼び出しフラグを作成する。この設定も Call graphs 同様、チェックすると時間がかかる。 |
Wizard タブでおこなう設定は以上。出力される HTML 上のメニュー項目などを日本語化したいなら Expert タブを開き OUTPUT_LANGUAGE 欄を English から Japanese に変更しておく。
すべての設定が完了したら Run タブを開いて Run doxygen ボタンを押す。しばらく待つとドキュメント作成が完了する。
生成されたドキュメントが HTML なら index.html がトップページとなる。表示すると以下のようになる。
出力された内容が妥当なら Doxywizard のメインメニューから「File」→「Save」または「Save as...」を選んで設定を記録しておく。ファイル名や拡張子は何でもよい。標準では Doxyfile という名前になる。保存先もお好みで。私は Doxygen の作業用フォルダ直下に標準の名前で保存している。
CHM を生成する
Doxygen で Microsoft Compiled HTML Help (CHM) 形式、いわゆる CHM ファイルを生成する方法についてまとめる。CHM 生成には HTML Help Workshop が必要なのでインストールしていないなら本記事の HTML Help Workshop 欄を参考にセットアップしておく。完了したらインストール先の hhc.exe までのフルパスをメモする。
次に Doxywizard を起動して CHM ファイルを出力したいプロジェクトの Doxygen 設定ファイルを開く。続けて Expert タブ内の HTML を選び GENERATE_HTMLHELP 以降を以下のように設定する。
| 項目 | 内容 |
|---|---|
| GENERATE_HTMLHELP | チェックすることで、CHM ファイルの出力が有効になる。 |
| CHM_FILE | 出力するファイル名。プロジェクト名.chm とするのが分かりやすくてよいだろう。 |
| HHC_LOCATION | HTML Help Workshop の実行ファイルへのフルパス。メモっておいたパスを入力するか隣のボタンを押すと表示されるファイル ダイアログで hhc.exe を開く。 |
| CHM_INDEX_ENCODING | CHM ファイルを開いた時、目次タブに表示される項目のテキスト エンコーディング。日本語が含まれるなら Shift_Jis を設定する。そうしないと文字化けする。 |
環境と設定が適切ならドキュメント出力を実行することで CHM ファイルが生成されるはず。ファイルを開くと以下のような感じになる。
キーワードによる絞り込みや検索も有効なので、かなり便利。リファレンスを配布する相手が Windows ユーザーなら検討してみる価値のある形式である。