Doxygen ドキュメント生成ツール "実践編"

概要編 Doxygenを使ってドキュメントを生成する手順は次のとおりです.

設定ファイルの生成
設定ファイルの編集
ドキュメントの生成

設定ファイルの編集をしっかりと行えば美しいドキュメントを生成することが出来ます. 設定ファイルの生成と編集は最初だけ行えば良く,ソースコードを編集/更新した後はドキュメントの生成だけで済みます. ここではC/C++言語をHTMLドキュメントへとドキュメンテーションする手順を紹介しています. それでは順に見て行きましょう.

設定ファイルの生成

次のコマンド1個で設定ファイルが生成されます.


doxygen -g

ドキュメント化したいソースコードのあるディレクトリへ移動してから生成すると楽が出来ます. このコマンドでDoxyfileという名前の設定ファイルが生成されます.


doxygen -g "ファイル名"

とすることで生成する設定ファイルの名前を任意に指定することも出来ます.

設定ファイルの編集

デフォルト設定でも十分ですが,エンコーディングや言語,プロジェクト名などは変更したいところです. 設定ファイルはお気に入りのテキストエディタで開いて編集しましょう. デフォルトでは次のような内容になっています.

ファイル先頭にはDoxygenの情報と設定ファイルの書き方が記してあります. 例えば,ハッシュマーク # に続く文字はコメントになる,書き方は タグ = 値 である(値は複数書ける場合もある),空白文字を含む値を書く時はクオート " " で囲む,といったことが書いてあります.

Doxygen情報と記法説明
プロジェクトに関する設定
ビルドに関する設定
警告や進行状況に関する設定
入力ファイルに関する設定
ソースコード閲覧機能に関する設定
クラス一覧の索引に関する設定
HTML出力に関する設定
LaTeX出力に関する設定
RTF出力に関する設定
manページ出力に関する設定
XML出力に関する設定
DOCBOOK出力に関する設定
AutoGen出力に関する設定
Perlモジュール出力に関する設定
プリプロセッサに関する設定
外部参照に関する設定
dotツールに関する設定

設定ファイルの項目は上述の順に並んでいます. 中でも重要な設定項目は太字で示しました.

まずはじめはプロジェクトに関する設定からです. ドキュメントのタイトルともなるプロジェクト名を適当な名前へ変更してみましょう.


PROJECT_NAME = "Lorem Ipsum"

次に出力言語を設定します. デフォルトは英語です. 日本語のドキュメントが良い場合は次のようにします.


OUTPUT_LANGUAGE = Japanese

今回はC言語のソースコードをドキュメンテーションするので,C言語への最適化オプションを有効化すると良いでしょう.


OPTIMIZE_OUTPUT_FOR_C = YES

他にもロゴ画像を設定するためのPROJECT_LOGOや,リビジョン番号を指定するPROJECT_NUMBERなど細かな設定が行えます.

続いて入力ファイル,すなわちCソースコードに関する設定です. もし,設定ファイルとソースコードが違うディレクトリにある場合はソースコードの在処をDoxygenに教えます.


INPUT = /c/source/directory

この設定値が空の場合,Doxygenは設定ファイルのあるディレクトリにソースコードがあるものと解釈します. ソースコードのキャラクタエンコードを指定することも出来ます. 基本的にはデフォルト値のUTF-8で問題ありませんが,Shift JISなど他のエンコードでソースコードが保存されている場合はそれをココに指定します. 詳しい設定値はlibiconvを参照ください. 以下に例を示します.


INPUT_ENCODING = SHIFT_JIS

デフォルトではHTMLとLaTeXの2つへ出力されるようになっていますが,今回はLaTeXへの出力を無効にし,HTMLのみへ出力するよう変更しましょう.


GENERATE_LATEX = NO

HTMLの設定は特にデフォルトで問題ありませんが,テーマカラーの設定が可能であることを記しておきます. HTML_COLORSTYLEのHUE,SAT,GAMMA各値を変更することでお好みのテーマカラーへ仕上げることが出来ます. ここを参考に色をつくりあげましょう(ただし最大値/最小値が異なるので注意).

Graphvizをインストールすればグラフを生成できます. ここで言うグラフとは函数の呼び出し関係図やOOPで言うクラスの継承関係図のことです. これは視覚的にプログラムの概要を得ることが出来るため非常に役立ちます. デフォルトではクラス図のみを出力しますが,次の設定で函数の呼び出し図と被呼び出し図も出力できます.


HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES

グラフの出力フォーマットも指定できますが,デフォルトのpngが良いでしょう. 折角なので,グラフの背景を白から透明にしておきましょう.


DOT_TRANSPARENT = YES

特に重要という訳では無いですが,ドキュメントのソースコード閲覧機能を使うとドキュメントからもソースコードを読むことが出来るようになるため便利です. 次の設定で有効になります.


SOURCE_BROWSER = YES

ドキュメントの生成

お好みの設定に仕上がったらいよいよドキュメントの生成です.


doxygen Doxyfile

Doxyfileの部分は設定ファイル名です. これで同ディレクトリ下にhtmlと言う名のフォルダが作成され,その中にHTMLドキュメントが生成されました. index.htmlというファイルがホームページです. ホームページのエイリアス(ショートカット)を作っておくと便利ですね.

3294040914662591451 https://www.storange.jp/2015/07/doxygen.html https://www.storange.jp/2015/07/doxygen.html Doxygen ドキュメント生成ツール "実践編" 2015-07-28T21:25:00+09:00 https://www.storange.jp/2015/07/doxygen.html Hideyuki Tabata Hideyuki Tabata

200 200

72 72