はじめよう

実行ファイル doxygen は、ソースを解析してドキュメントを生成するメインプログラムです。より詳細な使用方法については、Doxygen の使い方を参照してください。

オプションとして、実行ファイル doxywizard が使用できます。グラフィカルなフロントエンドであり、doxygen が使用する設定ファイルを編集したり、グラフィカルな環境でdoxygen を実行したりできます。 Mac OS X では、doxywizard は Doxygen アプリケーションアイコンをクリックすることで起動できます。

以下の図は、ツール間の関係およびそれらの間の情報の流れを示します (複雑なように見えるのは、完璧を目指しているからに過ぎません):

Doxygenの情報の流れ

ステップ 0: お使いのプログラム言語がサポートされているかチェック

最初に、お使いのプログラム言語をdoxygenが認識する合理的可能性を確保しましょう。C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, D がデフォルトでサポートされます。特定のファイルタイプの拡張子について、特定のパーサーを使用するよう設定できます。詳細は、Configuration/ExtensionMappings を参照してください。また、プリプロセッサ・プログラムを使うことで、上記とは違った言語をサポートすることも可能です。詳細は、ヘルパーページを参照してください。

ステップ 1: 設定ファイルを作成する

doxygen は、設定ファイルを使用して、すべての設定を決定します。各プロジェクトは、それぞれに設定ファイルが必要です。プロジェクトは、単一のソースファイルだけでも構成できますが、ソースツリー全体でも構成できます。ツリーは再帰的にスキャンされます。

設定ファイルの作成を単純化するために、 doxygen に設定ファイルのテンプレートを作成させることもできます。コマンドラインから -g オプションを付けて doxygen を呼び出してください。

doxygen -g <config-file>

ここで <config-file> は設定ファイルの名前です。ファイル名が省略された場合は、Doxyfile という名前のファイルが作成されます。 <config-file> という名前のファイルがすでにある場合は、doxygen は、設定テンプレートを生成する前にそのファイルを<config-file>.bak という名前に変更します。ファイル名に - (マイナス記号) を指定すると、doxygen は標準入力 (stdin) から設定ファイルを読み込もうとします(訳注:-g を使わない場合の説明、-g の場合は逆)。これは、スクリプトに使えます。

設定ファイルのフォーマットは、(単純な) Makefile のフォーマットに類似しています。次のような、いくつかの代入文（タグ）からなります:

TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...

作成されるテンプレート設定ファイルのほとんどのタグは、デフォルト値のままにしておくことができます。設定ファイルの詳細については、設定を参照してください。

テキストエディタを使って設定ファイルを編集したくない場合は、doxywizard を参照してください。このGUIフロントエンドでは、doxygen の設定ファイルの生成、読み込み、書き込みができ、ダイアログでオプションを設定できます。

少数の C/C++ ソースとヘッダーファイルからなる小さなプロジェクトでは、 INPUT タグは空のままにできます。この場合 doxygen はカレントディレクトリのソースを検索します。

ソースディレクトリまたはツリーからなる大規模プロジェクトの場合、ルートディレクトリまたは複数ディレクトリを INPUT タグに指定し、1つ以上のファイルパターンを FILE_PATTERNS タグ(例えば *.cpp *.h)に追加します。パターンのうち1つとマッチするファイルだけが構文解析されます (パターンが省略された場合は、doxygenがサポートするタイプのファイルに対して、典型的なパターンのリストを使います。)。ソースツリーを再帰的に解析するには、RECURSIVE タグを YES にセットしなければなりません。解析されるファイルのリストをさらに微調整するために、EXCLUDE と EXCLUDE_PATTERNS タグを使うことができます。例えばソースツリーから test ディレクトリのすべてを除外するには、次のようにします：

EXCLUDE_PATTERNS = */test/*

doxygenは、ファイルの拡張子を見て解析方法を決めます。そのテーブルを示します。

拡張子	言語
.idl	IDL
.ddl	IDL
.odl	IDL
.java	Java
.cs	C#
.d	D
.php	PHP
.php4	PHP
.php5	PHP
.inc	PHP
.phtml	PHP
.m	Objective-C
.M	Objective-C
.mm	Objective-C
.py	Python
.f	Fortran
.for	Fortran
.f90	Fortran
.vhd	VHDL
.vhdl	VHDL
.tcl	TCL
.ucf	VHDL
.qsf	VHDL
.md	Markdown
.markdown	Markdown

他の拡張子のファイルは、C/C++ ファイルとして解析します。

もし既存の (従って doxygen が認識するドキュメントは一切付いていない) プロジェクトに対して doxygen を使い始めた場合でも、その構造や、ドキュメント化の結果について知ることはできます。それには、設定ファイルで、EXTRACT_ALL タグを YES に設定する必要があります。すると、doxygen は、ソース中のあらゆる物にドキュメントが付けられているかのごとく振る舞います。

その結果、EXTRACT_ALL が YES に設定されてさえいれば、ドキュメントのないメンバーがあっても警告が生成されません。

既存のソフトウェア作品を解析するに当たっては、ソースファイル中での、(ドキュメント付けられている) 実体とその定義とのクロスリファレンスを取ることが役に立ちます。 SOURCE_BROWSER を YES に設定すると、doxygen は、そのようなクロスリファレンスを生成します。 INLINE_SOURCES を YES に設定すると、ドキュメント内に直接ソースコードを取り込むこともできます (たとえば、コードのレビューアにとって役に立つでしょう)。

ステップ 2: doxygen を実行する

ドキュメントを生成するには、次のように入力します。

doxygen <config-file>

設定しだいで、出力ディレクトリの中に、html, rtf, latex, xml, man、docbook ディレクトリなどが生成されます。名前からわかるように、これらディレクトリには、HTML, RTF, , XML および Unix-Man ページ、DocBook形式のドキュメントが格納されます。

デフォルトの出力先ディレクトリは、doxygen の起動ディレクトリと同じです。出力先のルートディレクトリは、OUTPUT_DIRECTORY を使って変更できます。出力先ディレクトリ内での、ファイル形式用ディレクトリは、設定ファイルで、 HTML_OUTPUT、RTF_OUTPUT、 LATEX_OUTPUT、XML_OUTPUT、 MAN_OUTPUT 、DOCBOOK_OUTPUTタグを使って指定できます。もし出力先ディレクトリが存在しないならば、doxygen はそれを作成しようとします (しかし、mkdir -p のように全体のパスを再帰的に作成したりは しません)。

HTML 出力

生成された HTML ドキュメントを見るには、HTML ブラウザで html ディレクトリの index.html ファイルを開きます。カスケーディング・スタイルシート (CSS) をサポートするブラウザ (作者は、Mozilla Firefox、Google Chrome、Safari、時にはIE8/IE9、Opera を使って結果をチェックしています) を使えば、最良な形で結果を見ることができます。

HTML セクションのいくつかの機能 (GENERATE_TREEVIEWや検索エンジンなど) は、Dynamic HTML と Javascript をサポートするブラウザを必要とします。

LaTeX 出力

生成される $\mbox{\LaTeX}$ ドキュメントは、まず $\mbox{\LaTeX}$ コンパイラを使ってコンパイルする必要があります(作者は、Linux,MacOSXでは最新の teTeX を、WindowsではMikTexを使います) 。生成されるドキュメントをコンパイルする手順を簡素化するために、doxygen は Makefile を latex ディレクトリに書き込みます(Windows環境では、バッチファイル make.bat も生成されます)。 (訳注:Windows環境では、W32TeX をTeXインストーラを使ってインストールし、LATEX_CMD_NAMEに"platex -kanji=utf8"を設定しましょう。手っ取り早く環境構築できます。)

Makefile の内容とターゲットは、USE_PDFLATEX の設定に依存します。不可 (NO) に設定されていた場合、latex ディレクトリで make と打ち込めば、refman.dvi と呼ばれる dvi ファイルが生成されます。このファイルは xdvi を使って見ることができます。また、make ps と打ち込む (これには dvips を必要とします) ことで PostScript ファイル refman.ps に変換できます。

一枚のページに 2ページ分を表示させるには、代わりに、make ps_2on1 を使用してください。結果として得られた PostScript ファイルは PostScript プリンタに送ることができます。もし PostScript プリンタが手元になければ、ghostscript を使って、PostScriptファイルを、お使いのプリンタ用に変換してみてください。

ghostscript インタプリタをインストールしてあれば、PDF への変換も可能です。 make pdf (または make pdf_2on1) とタイプするだけです。

PDF 出力を最良形で見るには、 PDF_HYPERLINKS タグと USE_PDFLATEX タグを YES に設定してください。こうすれば、Makefile には、refman.pdf を直接ビルドするのに必要なターゲットだけが書き込まれます。

RTF 出力

doxygenは、RTF 出力を、refman.rtf と呼ばれる単一のファイルに合成します。このファイルは Microsoft Word にインポートできるように最適化されています。情報によっては、いわゆるフィールドを使ってエンコードされます。実際の値を表示するには、すべて選択 (編集 - すべて選択) してから、フィールド更新 (右クリックしてドロップダウン・メニューからオプションを選びます) してください。

XML 出力

XML 出力は、Doxygenが集めた情報の塊で、それを構造化したものです。クラス、名前空間、ファイルなど各要素にそれぞれの XML ファイルがあり、index.xml と呼ばれるインデックス・ファイルもあります。

combine.xslt というXSLT スクリプトファイルも生成されるので、XML ファイルを単一のファイルに合成できます。

Doxygen は、2つの XML スキーマファイル、index.xml 用の index.xsd と要素用の compound.xsd を生成します。このスキーマファイルには、含まれる要素とそれらの属性、および構造が記述されます。すなわち、XMLファイルの文法が記述されているので、確認したり、XSLTスクリプトの操作に使うことができます。

addon/doxmlparser ディレクトリにはパーサーライブラリがあり、doxygenのXML出力を徐々に読むために使えます。(ライブラリのインタフェースについては、addon/doxmlparser/include/doxmlintf.h を参照してください)

Man ページ出力

生成される man ページは、man プログラムを使って見ます。 man ディレクトリが man パス (MANPATH 環境変数を参照) に含まれていることを確認する必要があります。 man ページのフォーマットには能力に制限があるので、クラス図、クロスリファレンス、式など一部の情報が失われる可能性があります。

ステップ 3: ソースのドキュメント付け

ソースにドキュメントを付けることをステップ 3 として提示していますが、新しいプロジェクトでは、もちろんステップ 1 でやるべきことです。ここでは、コードはすでに記述されていて、その API だけでなく、内部や関連する設計についてもドキュメントを生成したいという状況を想定して、話を進めます。

設定ファイルで、EXTRACT_ALL オプションが NO(デフォルト) に設定されている場合、doxygenがドキュメントを出力するのは、ドキュメント付けされた ファイル、クラス、名前空間についてだけです。じゃあ、これらにはどうやってドキュメントを付けてやればよいのでしょう。メンバー、クラス、名前空間に対して付けるには、基本的に 2通りの方法があります。

メンバーやクラス、名前空間の宣言や定義の前に、特殊な ドキュメントブロックを置きます。ファイル、クラス、名前空間のメンバーに対しては、直後にドキュメントを置くこともできます。

特殊ドキュメントブロックについて、詳しくは特殊なコメントブロックを参照してください。
特殊ドキュメントブロックを、どこか別の場所 (他のファイルや位置)に配置し、かつ、ドキュメントブロック内に 構造化コマンド を置きます。構造化コマンドは、ドキュメントブロックから、ドキュメント付けが可能な実体 (メンバー、クラス、名前空間、ファイルなど) へのリンクを作成します。構造化コマンドについて、詳しくは、他の場所のドキュメントを参照してください。

1番目のオプションの利点は、実体の名前を繰り返さなくて良いことです。

ファイルの場合は、前にドキュメント・ブロックを置く方法はないので、2番目のオプションしか使えません。もちろん、ファイルメンバー（関数、変数、typedef、define) には明示的な構造化コマンドは必要ありません。特殊ドキュメント・ブロックをその前後に入れるだけで良いのです。

特殊ドキュメントブロック内のテキストは、解析されてから、HTML やのファイルに書き出されます。

解析 (parsing) では、次のステップが実行されます:

Markdownフォーマットは、対応するHTMLか特殊コマンドに置き換えられます。
ドキュメント内部の特殊コマンドが実行されます。全コマンドの一覧は、特殊コマンドを参照してください。
空白で始まり、その後に 1つ以上のアスタリスク (*)、さらに 0個以上の空白が続く行では、空白とアスタリスクはすべて除去されます。
結果として空になる行は、段落区切りとして扱われます。ですので、読みやすくするための新規パラグラフのコマンドを書く手間が省けます。
ドキュメント付けされたクラスに対応する単語には、リンクが作成されます (その単語の前に % がついていなければ、リンクは作られず、% 記号は削除されます)。
テキストに特殊なパターンが見つかった場合、そのメンバーへのリンクが作成されます。自動リンク生成がどのように働くかについて、詳しくはセクションリンクの自動生成を参照してください。
ドキュメント内の HTML タグは、解析されて、等価に変換されて、ファイルが出力されます。サポートされているHTML タグの一覧は、HTMLコマンドを参照してください。

次のセクションに行く / インデックスに戻る

目次