はじめよう

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

実行ファイル doxytag は、ソースのない外部のドキュメント (すなわち、doxygen によって生成済みのドキュメント) への参照を生成したり、 検索エンジン用に検索インデックスを作成したりすることが要求される場合にのみ、 必要となります。 より詳細な使用方法については、セクション Doxytag usage を参照してください。

実行ファイル doxysearch は、検索エンジンを使用したい場合にのみ、 必要になります。 より詳細な使用方法については、セクション Doxysearch usage を参照してください。

オプションの実行ファイル doxywizard は、 doxygen によって使用される設定ファイルを編集するための GUI フロントエンドです。

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

Doxygen は、設定ファイルを使用して、すべての設定を決定します。 各プロジェクトは、それ自身の設定ファイルを持つべきです。 プロジェクトは、ただ一つのソースファイルから構成されていることもありますが、 再帰的にスキャンされるような全くのソースツリーから構成されているということもあります。

設定ファイルの作成を単純化するために、 doxygen は設定ファイルのテンプレートを作成することができます。 そのためには、-g オプションを付けて doxygen を呼び出します: 

doxygen -g <config-file>
ここで <config-file> は設定ファイルの名前です。 ファイル名が省略された場合は、Doxyfile という名前のファイルが作成されます。 <config-file> という名前のファイルがすでに存在していた場合は、 doxygen は、設定テンプレートを生成する前に <config-file>.bak という名前に変更します。 ファイル名として - (マイナス記号) を使用すると、 doxygen は標準入力 (stdin) から生成ファイルを読もうとします。

設定ファイルのフォーマットは、(単純な) Makefile のフォーマットに類似しています。 それは、以下の形式を持つ、いくつかの代入文を含んでいます:

TAGNAME = VALUE または
TAGNAME = VALUE1 VALUE2 ...

おそらく、生成されたテンプレート設定ファイルのほとんどのタグの値は、 デフォルト値のままにされることでしょう。

INPUT タグは、唯一、値を設定する必要のあるタグです。 設定ファイルについて、より詳しくは、セクション 設定 を参照してください。 少数の C/C++ のソースおよびヘッダーファイルから構成される小さなプロジェクトでは、 INPUT タグに後にファイル名を付け加えてやるとよいでしょう。

ソースディレクトリあるいはソースツリーから構成されるような大きなプロジェクトだと、 このやり方では、うんざりしてしまいます。 このような場合は、INPUT タグの後にルートとなるディレクトリ (複数可) を置き、 1つまたはそれ以上のファイルパターン (たとえば、*.cpp *.h) を FILE_PATTERNS に追加すべきでしょう。 パターンの1つにマッチするファイルだけが解析の対象となります (パターンが省略されると全ファイルが解析されます)。 ソースツリーを再帰的に解析するには、RECURSIVE に YES を設定しなければなりません。 解析対象ファイルのリストをさらに微調整するには、 EXCLUDE タグと EXCLUDE_PATTERNS タグが使用されます。

すでに存在しているプロジェクト (したがって、doxygen が理解できるようなドキュメントは一切付いていない) に対して doxygen を適用することから始めてみれば、 結果としてどのようなドキュメントが得られるかを理解することができるでしょう。 そうするためには、設定ファイルで、EXTRACT_ALL タグを YES に設定する必要があります。 すると、doxygen は、ソース中のあらゆる物にドキュメントが付けられているかのごとく 振る舞います。 EXTRACT_ALL が YES に設定されているかぎり、 ドキュメント付けられていないメンバーに関する警告は発せられない、 ということに注意してください。

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

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

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

doxygen <config-file>

doxygen は、出力ディレクトリ内に、html、\c rtf、latex および/または man といったディレクトリを作成します。 それらの名前が示唆するとおり、これらのディレクトリは、それぞれ、 HTML、RTF、 および Unix-Man ページのフォーマットで生成されたドキュメントを格納しています。

デフォルトの出力ディレクトリは、doxygen を起動したディレクトリです。 出力先のディレクトリは、設定ファイルの OUTPUT_DIRECTORY、 HTML_OUTPUT、 RTF_OUTPUT、 LATEX_OUTPUT、および MAN_OUTPUT を使用して変えることができます。 出力ディレクトリが存在しない場合は、doxygen がそれを作成します。

生成された HTML ドキュメントは、HTML ブラウザで、 html ディレクトリにある index.html ファイルを開けば、 閲覧することができます。 最良の結果を得るには、カスケーディングスタイルシートをサポートしている ブラウザを使用してください (作者は、現在、Netscape 4.61 を使用して、生成された出力をテストしています)。

生成された ドキュメントは、まず、 コンパイラによってコンパイルする必要があります (作者は、teTeX distribution version 0.9 を使用しています。これには、 version 3.14159 が含まれています)。 生成されたドキュメントのコンパイル処理を単純化するために、 doxygen は、latex ディレクトリに Makefile を書き込みます。 latex ディレクトリで make とタイプすると、dvi ファイル refman.dvi が生成されます (もちろん、make と呼ばれる自動化ツールを持っていると 仮定しています)。 その後、このファイルは、xdvi を使って表示させたり、 make ps とタイプして PostScript ファイル refman.ps に変換したり (dvips が必要です) することができます。 一枚のページに 2ページ分を表示させるには、代わりに、 make ps_2on1 を使用してください。 結果として得られた PostScript ファイルは PostScript プリンタに送ることができます。 もし PostScript プリンタを持っていないのならば、ghostscript を使って、 PostScript を、あなたのプリンタが扱える物に変換してみてください。 ghostscript インタプリタをインストールしてあれば、PDF への変換も可能です。 make pdf (または make pdf_2on1) とタイプするだけです。 PDF 出力で最良の結果を得るためには、 PDF_HYPERLINKS タグを YES に設定しておくべきです。

生成された man ページは、man プログラムを使って閲覧することができます。 man ディレクトリが man パス (MANPATH 環境変数を参照) に含まれていることを 確認する必要があります。 man ページのフォーマットの記述能力には何かと制限があるので、 いくつかの情報 (クラス図、クロスリファレンス、式など) は失われてしまう、 ということに注意してください。

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

ソースにドキュメントを付けることがステップ 3 として提示されていますが、 新しいプロジェクトでは、もちろんこれは、ステップ 1 でやるべきことです。 ここでは、すでにいくつかのコードを持っており、その API と、おそらくは 内部についても記述してある、ナイスなドキュメントを生成するのに doxygen を使いたいと思っている、と仮定します。

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

  1. メンバーやクラス、名前空間の宣言や定義の前に、 専用ドキュメントブロックを置きます。 ファイル、クラス、名前空間のメンバーに対しては、 直後にドキュメントを置くこともできます。 専用ドキュメントブロックについて、より詳しくは 専用ドキュメントブロック を参照してください。
  2. 専用ドキュメントブロックをどこか別の場所 (他のファイルや他の位置) に配置し、かつ、ドキュメントブロック内に 構造化コマンドを置きます。 構造化コマンドは、ドキュメント付けできる決められた実体 (メンバー、 クラス、名前空間、ファイルなど) に、ドキュメントブロックをリンクします。 構造化コマンドについて、より詳しくは、構造化コマンド を参照してください。
ファイルは、2番目のやり方でのみ、ドキュメント付けすることができます。 専用ドキュメントブロック内のテキストは、HTML や の出力ファイルに書かれる前に解析されます。

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

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

Doxygen manualに対してTue Oct 16 12:04:38 2001に生成されました。 doxygen1.2.11.1 の開発者: Dimitri van Heesch, © 1997-2001