外部ドキュメントへのリンク

自分のプロジェクトが外部のライブラリやツールに依存している場合、doxygenを実行するたびにそのソースすべてを含めるのは、控えたい理由がいくつかあります。

ディスク容量:

ドキュメントによっては、doxygenの出力ディレクトリの外部、たとえばウェブ上のどこかから得られるでしょう。ローカルの出力ディレクトリにドキュメントを生成するのでなく、そのページへのリンクを張りたいでしょう。

コンパイル・スピード:

外部プロジェクトというのは、ご自身のプロジェクトとは違うタイミングで更新されるでしょう。変更がないのに外部プロジェクトのソースを解析させても意味がありません。

メモリ:

ソースツリーがかなり大きい場合、全ソースを解析させると、ご自身のシステムメモリがかなり消費されます。ソースをいくつかの"パッケージ"に別ければ、一つのパッケージのソースをdoxygenに解析させることができ、そのパッケージが依存するほかのパッケージは外部リンクすれば、メモリを節約できるでしょう。

入手度:

doxygenでドキュメントづけされたプロジェクトによっては、ソースが得られないものもあるでしょう。

著作権:

外部パッケージとそのドキュメントの著作権が他の方にある場合、ご自身のドキュメントにそのコピーを含めるより、参照するほうが良い、あるいは必要でしょう。著者が再配布を禁止している場合、必要です。著者が再配布の前提条件として許可条件に従うことを要求していても、ご自身はそのような条件に縛られたくない場合、そのドキュメントのコピーを参照するようにしたほうが、コピーをインクルードするより好ましいでしょう。

上記のうちのどれかが該当する場合、doxygenのタグファイル・メカニズムを使えます。タグファイルは、基本的に外部ソースにあるエンティティーを簡潔に表現するものです。doxygenはタグファイルを生成することも読むこともできます。

プロジェクトのタグファイルを生成するには、タグファイルの名前を、設定ファイルの GENERATE_TAGFILE の後に置くだけです。

一つ以上の外部プロジェクトの出力をご自分のプロジェクトと結合するには、設定ファイルで、 TAGFILES の後にタグファイル名を指定します。

タグファイルは、doxygenを実行した位置からの相対的な、ドキュメントの場所を含むだけです。他のプロジェクトのタグファイルをインクルードするときは、外部ドキュメントがご自分のプロジェクトと比較してどこにあるかを指定しなければなりません。これを行うには、設定ファイルで、TAGFILES の後にタグファイルへの(相対的な)場所を指定します。相対パスを使うのであれば、プロジェクトのHTML出力が生成されるディレクトリとの相対でなければなりません。つまり、あるプロジェクトのHTML出力ディレクトリから、リンクされる他のプロジェクトのHTML出力への、相対パスです。

例:: ext1 と ext2 という２つの外部プロジェクトを使う proj プロジェクトがあるとします。ディレクトリ構造を以下に示します。

<root>
  +- proj
  |   +- html               projのHTML 出力ディレクトリ
  |   +- src                projのソース
  |   |- proj.cpp
  +- ext1
  |   +- html               ext1のHTML 出力ディレクトリ
  |   |- ext1.tag           ext1のタグファイル
  +- ext2
  |   +- html               ext2のHTML 出力ディレクトリ
  |   |- ext2.tag           ext2のタグファイル
  |- proj.cfg               projのdoxygen 設定ファイル
  |- ext1.cfg               ext1のdoxygen 設定ファイル
  |- ext2.cfg               ext2のdoxygen 設定ファイル

: この場合、設定ファイルの関連する部分は以下のようになります。

proj.cfg:

OUTPUT_DIRECTORY  = proj
INPUT             = proj/src
TAGFILES          = ext1/ext1.tag=../../ext1/html \
                    ext2/ext2.tag=../../ext2/html

ext1.cfg:

OUTPUT_DIRECTORY  = ext1
GENERATE_TAGFILE  = ext1/ext1.tag

ext2.cfg:

OUTPUT_DIRECTORY  = ext2
GENERATE_TAGFILE  = ext2/ext2.tag

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