doxygenの使用例 - Informatik-Wiki

なんでもありのdoxygen

doxygen はオープンソースで出ている静的なソース解析＆ドキュメント化ツールです。
昔から使っていますが高機能化と他言語対応がすすんで今やなんでもありになった感があります。
それだけに、新しい機能について理解し、使いこなすのも難しくなっています。
設定次第でいくらでも細かい作業を行うので、逆に情報過多になり過ぎてしまうきらいもあります。
自分は専ら新しい作業で既存のソースの理解を早めるために、ソースブラウズ用出力を生成しています。

Graphviz連携

Graphviz はあまりにも有名なグラフィックツールライブラリです。
これと連携する事で、ずいぶんと見栄えのするドキュメントを作れる様になります。
そのためにはGraphvizを入手してあらかじめインストールしておく必要があります。
doxygenの設定例としては、以下のようになります。Graphvizを使用するときは、DOT使用の設定にて
その指定を行います。

• HAVE_DOT = YES # DOTを使用する。グラフィカルな出力が有効になる。
  • ここをYESにしないとグラフィック出力しません。
• DOT_FONTNAME = MSGOTHIC_TTC # Graphvizが使用するフォント。指定しなくても可。
• DOT_FONTSIZE = 9 # 同サイズ。指定しなくても可。
• DOT_FONTPATH = C:\WINDOWS\Fonts # Graphvizに使わせたいフォントファイルが存在するPATH。指定しなくても可。
  • 上の３つは設定しなくてもデフォルト設定で適当に出力します。
  • イメージ化した日本語が化けるときに変更してみてください。
• CLASS_GRAPH = YES # 全体のクラス図
• COLLABORATION_GRAPH = YES # コラボレーション図
• GROUP_GRAPHS = YES # グループ図
• UML_LOOK = NO # UMLっぽい外見にする
• TEMPLATE_RELATIONS = YES # テンプレート関連図
• INCLUDE_GRAPH = YES # includeツリー図
• INCLUDED_BY_GRAPH = YES # 逆includeツリー図
• CALL_GRAPH = YES # 呼び出しツリー図
• CALLER_GRAPH = YES # 呼び元ツリー図
• GRAPHICAL_HIERARCHY = YES # グラフィカル階層図
• DIRECTORY_GRAPH = YES # ディレクトリ図
• DOT_IMAGE_FORMAT = png # 出力イメージファイルのフォーマット
• DOT_PATH = D:/TOOLS/Entwicklung/doxygen/ATT/Graphviz/bin # Graphvizをインストールした場所
• DOT_GRAPH_MAX_NODES = 20 # 一個の図に入れるノードの最大個数
  • これをあまり多めにすると絵がでかくなりすぎて見難くなります。
• DOT_CLEANUP = YES # クリーンナップする
• HTML_DYNAMIC_SECTIONS = NO # JavaScriptを使ってイメージファイルを閉じたり開いたり出来る様なページにする

HTML HELP WORKSHOPとの連携

doxygenで最もポピュラーな出力形態はHTMLだと思いますが、これを行うと、膨大な数のファイルが作られて
結構管理も大変になります。これを軽減する方法のひとつにWindowsでお馴染みのchmファイルを生成する、
という手段があげられます。

HTML HELP WORKSHOP

マイクロソフトはMSDNのリソースの一部としてHTML HELPコンパイラの開発セットを無料公開していました。
これを使用すると、プロジェクトを生成してHTMLファイルをまとめてひとつのchmファイルに統合することが
たやすく出来ます。

ダウンロードサイト は変わるかもしれないので
その都度捜す方が確かです。

doxygenの HTML HELP 支援機能

doxygenではHTML HELP生成を有効にしてchmファイル名を設定ファイルに書いておくと、
勝手にこのHTML HELP WORKSHOPのプロジェクトファイルを生成し、HTMLヘルプコンパイラを起動して
chmファイルを作ってくれます。そのために必要な設定は以下の通りです。注意点は、
HTML HELPコンパイラで日本語を扱うときは、Shift_Jisでないと化け化けになる、という事です。
このため、UTF-8などで書いたソースを扱うときは、途中にフィルタをかませる必要があります。
以下、設定ファイル例の主要ポイントです。

• DOXYFILE_ENCODING = UTF-8 # 元のソースのエンコーディングはUTF-8だった
• OUTPUT_LANGUAGE = Japanese-en # 出力言語は日本語＋英語メニューに設定。メニュー文字化け防止のため
• INPUT_ENCODING = Shift_Jis # doxygenに渡すソースのエンコーディングをShift_Jisに設定。HTML HELP用。
• INPUT_FILTER = "D:\cygwin\bin\iconv -c -f UTF-8 -t SHIFT-JIS" # Cygwinのiconvを使ってUTF-8→Shift-Jis変換
  • D:\cygwinにcygwinがインストールされている場合。iconvは単体版も出ているので利用可。
  • iconvでなくてもnkfなどコード変換フィルタ系ツールが使えれば置き換え可能。
    • 入力テキストのエンコーディングを変換してstdoutに出力できるタイプ。
• FILTER_SOURCE_FILES = YES # ドキュメント出力部だけでなくソース全部をUTF-8→Shift-Jis変換対象にする
• GENERATE_HTML = YES # HTML生成を有効にする
• GENERATE_HTMLHELP = YES # HTML HELP生成を有効にする
• CHM_FILE = myproject.chm # HTML HELPファイル名を指定する
• HHC_LOCATION = "C:/Program Files/HTML Help Workshop/hhc.exe" # HTML HELPコンパイラPATHを指定する
• GENERATE_CHI = NO # (OPTIONAL) CHIファイル生成を無効（YESで有効）にする
• CHM_INDEX_ENCODING = Shift_Jis # CHMインデックスのエンコーディングを指定する（本文に合わせてShift_Jisに指定）
• BINARY_TOC = YES # TOCをバイナリにする
• TOC_EXPAND = NO # TOCを開かない

Linuxでchmを作るには

今のところHTML HELPはWindowsでしか動作しませんが、wineを使えばLinux上でも動作するようです。

chmが出来たら

chmは元がHTMLなので、文書内にURLを書いておくと外部ドキュメントへのリンクになります。
また、chmをpdfなどに変換するツールも色々と出ているので、pdf化して配布することも出来る様になります。

ドキュメント分割

doxygenは相当巨大なソースセットでもこつこつとドキュメント変換してくれます。
しかし、毎回全ソースを変換していたのでは時間もかかり非効率です。
効率を上げるために、ドキュメント対象（設定ファイルでいうINPUTで指定するPATHを
小型化して、出力ファイルのひとつとしてTagfileを生成する、というのもひとつの方法です。
こうして生成したTagfileを別のdoxygen設定ファイル上で参照する事が出来ます。

• INPUT = D:/myproject/mysrc/part1
  • 同様に、part2というプロジェクトが存在するという前提
• GENERATE_TAGFILE = myTagfile_part1.xml
  • part1用のTagfileがmyTagfile_part2.xmlという名前で生成されている、という前提です。
  • 同様に、part2用のTagfileがこの名前で生成されます。
• TAGFILES = myTagfile_part2.xml
  • 外部のTagfileを参照するのはこの設定です。スペースで区切って複数並べることも出来ます。

ドキュメント分割するときの注意

doxygenはただでさえたくさんのPATH設定を使用しています。
doxygenを動作させるPATH、設定ファイルが存在するPATH、設定ファイル中に書かれた入力PATHや出力PATH。
これ等が複雑に絡み合っているのでTagfilesを使用する時は、設定ファイルとINPUTのPATHの位置が
うまく合ってないとちゃんと処理できないことがあります。安全な事例としては、以下のようになります。

• /myproject/mysrc
  • ここ（ソースディレクトリの頂点）にDoxyfile_part1を置く
    • GENERATE_TAGFILE = /myproject/mydoc/part1/myTagfile_part1.xml
    • TAGFILES = myTagfile_part2.xml=/myproject/mydoc/part2
    • 参照指定のときは、相対PATH、絶対PATHのほか、ファイル名＝PATHの形式が可能
  • ここ（ソースディレクトリの頂点）にDoxyfile_part2を置く
    • GENERATE_TAGFILE = /myproject/mydoc/part2/myTagfile_part2.xml
    • TAGFILES = myTagfile_part1.xml=/myproject/mydoc/part1
    • 参照指定のときは、相対PATH、絶対PATHのほか、ファイル名＝PATHの形式が可能
• /myproject/mysrc/part1
  • part1のソースツリー
• /myproject/mysrc/part2
  • part2のソースツリー
• /myproject/mydoc/part1
  • ソースのpart1のドキュメント出力先
  • ここにmyTagfile_part1.xmlを出力する
• /myproject/mydoc/part2
  • ソースのpart2のドキュメント出力先
  • ここにmyTagfile_part2.xmlを出力する