よくある質問

HTML のインデックスページに情報を載せるには？

コメントブロック内で \mainpage コマンドを使ってください。

/*! \mainpage My Personal Index Page
 *
 * \section intro_sec Introduction
 *
 * This is the introduction.
 *
 * \section install_sec Installation
 *
 * \subsection step1 Step 1: Opening the box
 *  
 * etc...
 */

クラス・ファイル・名前空間のメンバーの一部または全部にドキュメントがないのは？

次のことをチェックしてください。:

1. クラス・ファイル・名前空間がドキュメント付けされていますか? でなければ、設定ファイルで EXTRACT_ALL を YES にしないと、ソースから抽出されません。
2. メンバーは private ですか? であれば、 EXTRACT_PRIVATE を YES にすればドキュメントに出力されます。

3. セミコロン(MY_MACRO()のような)で終了していない関数マクロがクラスにありませんか? あれば、doxygenのプリプロセッサにそれを削除するよう指示してください。

   これには、設定ファイルで次のような設定をします。

   ENABLE_PREPROCESSING   = YES
   MACRO_EXPANSION        = YES
   EXPAND_ONLY_PREDEF     = YES
   PREDEFINED             = MY_MACRO()=

   詳しいことは、マニュアルの 前処理 のセクションを読んでください。

EXTRACT_ALL を NO にしたら、関数がドキュメントに出力されないのですが

グローバルな関数や、変数、列挙型、型定義、defineを出力するには、これらコマンドがあるファイルをドキュメント付けする必要があります。 それには、\file(か@file)コマンドをコメントブロックに指定してください。

または、\ingroup コマンドを使ってメンバーすべてをグループ(またはモジュール)に入れて、さらに \defgroup コマンドを含むコメントブロックを使って、グループにドキュメント付けします。

メンバー関数や名前空間の一部となっている関数の場合は、そのクラスや名前空間をドキュメント付けしてください。

独自の拡張子ファイルが(正確に)(もはや)解析されない。

Doxygenでは、入力(INPUT タグで)指定したファイルと、指定された拡張子(FILE_PATTERNS) にマッチするファイルのみ、解析します。 EXCLUDE で指定された拡張子にマッチするファイル、EXCLUDE_PATTERNSに指定されたパターンにマッチするファイルは、一覧から除外されます。

過去には、未知の拡張子のファイルも含めて解析していましたが、結果として望ましくないことがありました。バージョン1.8.8以降では、ファイル拡張子に対応するパーサーを指定していただくようになっています。これは、EXTENSION_MAPPING によって指定できます。指定されていないファイルについては、内容が無視されます。

一部のコード断片をdoxygenに無視させるにはどうすればよいですか?

現在最も簡単な方法は、 \cond コマンドのコメントブロックを対象コードの最初に追加し、\endcond コマンドのコメントブロックを対象コードの最後に追加します。当然ながら、同一ファイル内で行ってください。

でも、doxygen のプリプロセッサを使う方法もあります。

#ifndef DOXYGEN_SHOULD_SKIP_THIS

 /* doxygenにスキップさせたいコード */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

と隠すべきブロックのあたりに置き、 設定ファイルで次のように指定すると、

  PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

ブロック全体がPREPROCESSING = YESである限り、スキップされます。

クラスのドキュメントで <code>#include</code> の後にくるものを変えるにはどうすればよいですか?

パスの一部をユーザ定義で除去するには、STRIP_FROM_INC_PATH を使うのが常套手段です。

次のようにクラスをドキュメント付けする方法もあります。

/*! \class MyClassName include.h path/include.h
 *
 *  Docs for MyClassName
 */

こうすれば、
#include <path/include.h> が、クラスMyClassName の定義を実際に含むヘッダファイルの名前に関わらず、そのクラスドキュメントに出力されます。

角括弧の代わりに引用符を使ってインクルードファイルをインクルードすべきことを示すには、次のようにします。

/*! \class MyClassName myhdr.h "path/myhdr.h"
 *
 *  Docs for MyClassName
 */

圧縮 HTML との組み合わせでタグファイルを使うにはどうすればよいですか?

たとえば、HTML 圧縮ファイル a.chm から別の HTML 圧縮ファイル b.chm を参照するには、b.chm 内のリンクは次の形式になっていなければなりません。

<a href="b.chm::/file.html">

しかし、残念ながら両方の圧縮ファイルが同じディレクトリにないと働きません。

従って、すべてのプロジェクトについて、生成される index.chm ファイルをユニークな名前に変更し、 .chm ファイルすべてをひとつのディレクトリに収めなければなりません。

たとえば、a というプロジェクトがあって、プロジェクト b へはタグファイル b.tag を使って参照するものとします。この場合、a プロジェクトのindex.chm をa.chm に変更し、b プロジェクトの index.chm を b.chm に変更します。 a プロジェクトの設定ファイルでは、次のように書きます。

TAGFILES = b.tag=b.chm::

または、installbox を使って次のようにリンクをはる方法もあります。

installdox -lb.tag@b.chm::

HTML ページごとに上に置かれるクイックインデックスがいやです

"DISABLE_INDEX" を YES にすればインデックスを無効にできます。 その上で独自のヘッダを書いて、そのヘッダファイルを "HTML_HEADER" に指定します。

独自の html ヘッダファイルを使いたいだけなのに、HTML 出力全体が変わってしまうのですが

doxygen が生成する doxygen.css というスタイルシートをインクルードし忘れたのでしょう。HTML ページの HEAD セクションで次のように指定してください。

<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">

なぜ doxygen は Qt を使うのですか?

最大の理由は、殆どの Unix, Windows プラットフォームにも通用する抽象クラスとして、QFile, QFileInfo, QDir, QDate, QTime, QIODevice が定義されているからです。 もうひとつは、堅牢でバグのないユーティリティクラスとして、QList, QDict, QString, QArray, QTextStream, QRegExp, QXML などがあるからです。

GUI フロントエンドのdoxywizard は、まさにGUIに Qt を使っています。

対象ディレクトリにある test というディレクトリを除外するにはどうすればよいですか?

設定ファイルで次のような除外パターンを入力してください。

EXCLUDE_PATTERNS = */test/*

テキストの中に、自動的にクラス MyClass へのリンクが生成されてしまいます。

一部の箇所でこれを阻止するにはどうすればよいですか?

クラス名の前に % を %MyClass のように置いてください。すると % は削除され、ワードはリンクされません。

X プログラミングが好みです。それでも doxygen は使えますか?

いいえ、doxygen は読み込んだ対象の構造を解釈する必要があります。 時間を厭わないようでしたら、幾つかオプションはあります。

• X の文法が C や C++ に近いなら、src/scanner.l を少し調節するのはそれほど難しくないかもしれません。doxygen が直接サポートする他の言語 (Java, IDL, C#, PHP) についてもこれは実施されています。
• X の文法がいくらか違うようであれば、C や C++ に十分近づけるために X を翻訳する入力フィルタを書いて、doxygen に解釈させることはできるでしょう (この方法は VB, オブジェクトパスカル、Javascript でもとられています http://www.stack.nl/~dimitri/doxygen/download.html#helpers を参照してください)。
• X の文法がまったく違う場合は、X パーサを書いて、src/scanner.l(タグファイルを読む src/tagreader.cpp ) のようにシンタックスツリーを作るバックエンドを書くこともできるでしょう。

わけのわからないメッセージがでました。"input buffer overflow, can't enlarge buffer because scanner uses REJECT"

doxygen の語いスキャナのルールとして、一度に256K 以上の入力文字にマッチする場合に起こります。 この現象は生成されたファイルが非常に大きな場合(256K 行以上)で見たことがあります。組み込みの プリプロセッサが空ファイル(256K 行以上の改行つきで)に変換したのです。 他に、コードに256K 文字以上の行がある場合にも起こりえます。

もしこのような現象が起こって、解消を依頼する場合は、メッセージを引き起こしたコードの断片をこちらへ送ってください。問題を回避するには、ファイルにいくつか改行を入れたり、分割したり、EXCLUDE を使って入力からはずすなどしてください。

latex ディレクトリで make を動かすと、"TeX capacity exceeded"というメッセージが出ました。

texmf.cfg ファイルを編集してさまざまなバッファのデフォルト値を増やし、"texconfig init" を実行してみてください。

STL クラスを介した依存関係が dot グラフに現れないのはなぜですか?

BUILTIN_STL_SUPPORTオプションをオンにしない限り、doxygen は STL クラスを認識しません。

PHP5とWindowsで検索エンジンにトラブルが起こります。

こちらでヒントを探してください。

コマンドラインからdoxygen設定を定義できますか?

いいえ、コマンドラインオプションではできません。しかし stdin から読むことはできるので、パイプを使えば可能です。次に、設定ファイルのオプションをコマンドラインからオーバーライドする例を示します(unix 環境を想定しています)。

( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -

Windowsでは、次のコマンドを使います。

( type Doxyfile & echo PROJECT_NUMBER=1.0 ) | doxygen.exe -

同じ名前でいくつもオプションを指定した場合は、doxygen は最後の指定を使います。 既定のオプションに追加するには、+= 演算子を使ってください。

doxygen という名の由来は?

documentation と generator から来ています。

documentation -> docs -> dox
generator -> gen

lex と yacc に没頭していた頃、多くが "yy" で始まっていることから、"y" がスリップインしてきて発音しやすくなりました(Docs-ee-gen と長い "e" が付くのがいい発音です)。

doxygen を開発した理由は?

昔 Qt ライブラリ(今もhttp://qdbttabular.sourceforge.net/ で公開しており、Sven Meyerがメンテナンスしています。)ベースのGUI ウィジェットを書いたことがあります

Qt は綺麗なドキュメントを生成してくれました(公開されていない内部ツールが使われていました)。自分でも似たドキュメントを書きましたが、メンテナンスにてこずりました。それで自分で似たツールがほしくなりました。 Doc++を覗きましたが、充分とはいえませんでした(シグナルもスロットもサポート無しで、Qt のような好みの見栄えは得られませんでした)。それで独自のツールを書き始めたのです。

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