ドキュメント 変更履歴 拡張機能 例  
よくある質問

目次

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. メンバーはプライベートですか？その場合は、ドキュメントに表示されるように EXTRACT_PRIVATE を YES に設定する必要があります。

  3. クラスにセミコロンで終わらない関数マクロ（例：MY_MACRO()）はありますか？もしそうなら、Doxygen のプリプロセッサにそれを削除するように指示する必要があります。

    これは通常、設定ファイル内の次の設定に帰着します。

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

    詳細については、マニュアルの プリプロセッシング セクションをお読みください。

EXTRACT_ALL を NO に設定すると、関数がドキュメントに表示されません。

グローバル関数、変数、列挙型、typedef、および define をドキュメント化するには、\file (または @file) コマンドを含むコメントブロックを使用して、これらのコマンドが配置されているファイルをドキュメント化する必要があります。

または、\ingroup コマンドを使用してすべてのメンバーをグループ（またはトピック）に入れ、\defgroup コマンドを含むコメントブロックを使用してグループをドキュメント化することもできます。

メンバー関数または名前空間の一部である関数の場合は、クラスまたは名前空間のいずれかをドキュメント化する必要があります。

カスタム拡張子を持つファイルが（適切に）解析されません。

Doxygen は、（INPUT タグを介して）入力として指定され、（FILE_PATTERNS で言及されている）指定された拡張子に一致するファイルのみを解析します。ファイルリストは、EXCLUDE としてリストされているファイル、または EXCLUDE_PATTERNS で設定されたパターンに一致するファイルを除外することで縮小されます。

過去には、Doxygen は不明な拡張子を持つすべてのファイルを C ファイルとして解析していたため、望ましくない結果につながる可能性がありました。バージョン 1.8.8 以降、Doxygen では、特定のファイル拡張子に対してどのパーサーを使用するかを指示するマッピングを指定する必要があります。このマッピングは、EXTENSION_MAPPING タグを使用して指定します。マッピングが指定されていない場合、ファイルの内容は無視されます。

Doxygen に特定のコードフラグメントを無視させるには？

新しい最も簡単な方法は、\cond コマンドを持つコメントブロックを先頭に 1 つ、無視する必要があるコードの最後に \endcond コマンドを持つコメントブロックを 1 つ追加することです。これはもちろん、同じファイル内にある必要があります。

ただし、Doxygen のプリプロセッサをこれに使用することもできます。次のように記述した場合

#ifndef DOXYGEN_SHOULD_SKIP_THIS

 /* code that must be skipped by Doxygen */

#endif /* DOXYGEN_SHOULD_SKIP_THIS */

非表示にする必要があるブロックの周りに配置し、

  PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS

設定ファイルに入れると、ENABLE_PREPROCESSING が YES に設定されている限り、すべてのブロックが Doxygen によってスキップされます。

クラスドキュメントで #include の後に表示される内容を変更するには？

ほとんどの場合、STRIP_FROM_INC_PATH を使用して、ユーザー定義のパスの一部を削除できます。

クラスを次のようにドキュメント化することもできます。

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

Doxygen に次のように出力させるには

#include <path/include.h>

MyClassName の定義が含まれている実際のヘッダーファイルの名前に関係なく、クラス MyClassName のドキュメントに。

Doxygen にインクルードファイルが山括弧ではなく引用符を使用してインクルードする必要があることを示したい場合は、次のように入力する必要があります。

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

圧縮 HTML と組み合わせてタグファイルを使用するには？

ある圧縮 HTML ファイル a.chm から別の圧縮 HTML ファイル b.chm を参照する場合は、a.chm のリンクは次の形式にする必要があります。

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

残念ながら、これは両方の圧縮 HTML ファイルが同じディレクトリにある場合にのみ機能します。

その結果、すべてのプロジェクトで生成された index.chm ファイルの名前をユニークなものに変更し、すべての .chm ファイルを 1 つのディレクトリに入れる必要があります。

プロジェクトa がタグファイル b.tag を使用してプロジェクトb を参照しているとします。その場合、プロジェクトa の index.chm の名前を a.chm に、プロジェクトb の index.chm の名前を b.chm に変更できます。プロジェクトa の設定ファイルに次のように記述します。

TAGFILES = b.tag=mk:@MSITStore: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 を使用するのはなぜですか？

過去（バージョン 1.9.2 より前）では、Doxygen はさまざまなユーティリティクラスに Qt 2.x の一部を使用していました。これらは、その間に STL コンテナクラスに置き換えられました。

Doxywizard と呼ばれる GUI フロントエンドは、Qt の最新バージョンに基づいています。Doxygen 自体は GUI なしで使用することもできます。

ディレクトリツリーからすべてのテストディレクトリを除外するには？

設定ファイルに次のような除外パターンを記述するだけです。

EXCLUDE_PATTERNS = */test/*

Doxygen は、実行中のテキストのどこかにクラス MyClass へのリンクを自動的に生成します。特定の場所でそれを防ぐにはどうすればよいですか？

クラス名の前に % を付けます。例：%MyClass。Doxygen は % を削除し、単語をリンクなしのままにします。

私の好きなプログラミング言語は X です。それでも Doxygen を使用できますか？

いいえ、そのままでは使用できません。Doxygen は読み取るものの構造を理解する必要があります。時間をかけても構わないのであれば、いくつかのオプションがあります。

  • X の文法が C または C++ に近い場合、言語がサポートされるように src/scanner.l を少し調整するのはそれほど難しくないでしょう。これは、Doxygen で直接サポートされている他のすべての言語（つまり、Java、IDL、C#、PHP）に対して行われています。
  • X の文法が多少異なる場合は、Doxygen が理解できる C/C++ に十分に類似したものに X を変換する入力フィルターを作成できます（このアプローチは、VB、Object Pascal、および JavaScript で採用されています。 https://doxygen.dokyumento.jp/helpers.html を参照してください）。
  • 文法が完全に異なる場合は、X のパーサーを作成し、src/scanner.l（およびタグファイルを読み取る際の src/tagreader.cpp）と同様の構文木を生成するバックエンドを作成できます。

ヘルプ！不可解なメッセージ「input buffer overflow, can't enlarge buffer because scanner uses REJECT」が表示されます。

このエラーは、Doxygen の字句スキャナーに、一度に 256K を超える入力文字に一致するルールがある場合に発生します。これは、非常に大きな生成ファイル（>256K 行）で発生するのを確認しました。このファイルでは、組み込みプリプロセッサがそれを空のファイル（>256K の改行を含む）に変換しました。これが起こりうるもう 1 つのケースは、コードに 256K 文字を超える行がある場合です。

そのようなケースに遭遇し、修正してほしい場合は、メッセージをトリガーするコードフラグメントを送信してください。問題を回避するには、ファイルに改行をいくつか挿入するか、小さなパーツに分割するか、EXCLUDE を使用して入力から除外します。

この問題を回避する別の方法は、オプション付きの cmake コマンドを使用することです。

-Denlarge_lex_buffers=<size>

ここで、<size> は入力 (YY_BUF_SIZE) および読み取り (YY_READ_BUF_SIZE) バッファーの新しいサイズです。このオプションが指定されていない場合は、デフォルト値の 262144 (つまり、256K) が使用されます。

latex ディレクトリで make を実行すると、「TeX capacity exceeded」と表示されます。今、どうすればよいですか？

texmf.cfg ファイルを編集してさまざまなバッファーのデフォルト値を増やし、「texconfig init」を実行できます。

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

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

PHP5 および/または Windows で検索エンジンを動作させるのに問題があります。

どこを探すべきかについてのヒントについては、こちらをお読みください。

コマンドラインから Doxygen を設定できますか？

コマンドラインオプションからはできませんが、Doxygen は stdin から読み取ることができるため、パイプ処理できます。コマンドラインから設定ファイル内のオプションをオーバーライドする方法の例を次に示します（UNIX ライクな環境を想定）。

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

Windows コマンドラインの場合、次のようになります。

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

Windows Powershell の場合（バージョン 5.1 で確認済み）、次のようになります。

&{ type Doxyfile ; echo "PROJECT_NUMBER=1.0" } | doxygen -

同じ名前の複数のオプションが指定されている場合、Doxygen は最後のオプションを使用します。既存のオプションに追加するには、+= 演算子を使用できます。

Doxygen はどのようにしてその名前を得たのですか？

Doxygen の名前は、ドキュメントとジェネレーターという言葉を組み合わせて作られました。

documentation -> docs -> dox
generator -> gen

当時、私は lex と yacc を調べていて、多くのものが「yy」で始まっていたため、「y」が滑り込み、発音しやすくなりました（適切な発音は Docs-ee-gen で、「e」を長く発音します）。

Doxygen を開発した理由は何ですか？

私はかつて Qt ライブラリに基づいて GUI ウィジェットを作成しました（それは https://sourceforge.net/projects/qdbttabular/ でまだ利用可能ですが、2002 年から更新されていません）。Qt には、（公開したくなかった内部ツールを使用して）うまく生成されたドキュメントがあり、私は手作業で同様のドキュメントを作成しました。これは維持するのが悪夢だったため、同様のツールが必要でした。Doc++ を調べましたが、十分ではありませんでした（シグナルとスロットをサポートしておらず、私が好きになった Qt のルックアンドフィールを持っていませんでした）。そのため、独自のツールを書き始めました...

インターリーブされた出力を防ぐ方法

Doxygen のコンソール出力（つまり、メッセージと警告）をすべてリダイレクトすると、これがインターリーブされたり、予期しない順序になったりする可能性があります。これの技術的な理由は、stdout がバッファリングされる可能性があるためです。これは、Doxygen の -b を使用することで克服できます。たとえば、doxygen -b > out.txt 2>&1 のようにします。ただし、これにより少し時間がかかる可能性があることに注意してください。

次のセクションに進むか、インデックスに戻ります。