汎用設定変数

一般的な QDoc 設定変数を使用すると、QDoc がドキュメントを生成するために必要な各種ソースファイルの場所や、生成されたドキュメントを保存するディレクトリを定義できます。また、QDoc 自体に対して、出力や処理の挙動を制御するといった、わずかな調整を行うことも可能です。

codeindent

codeindent 変数は、QDocがコードスニペットを出力する際に使用するインデントのレベルを指定します。

QDocは当初、コードスニペットを周囲のテキストと容易に区別できるようにするため、コードのインデントに4スペースという固定値を使用していました。スタイルシートを使用して特定の種類のHTML要素の外観を調整できるため、このレベルのインデントが常に必要というわけではありません。

codelanguages

codelanguages 変数は、QDocが認識しないソースコード言語のリストを指定するもので、\code...\endcode ブロック内で使用できます。これにより、QDocが解析できない言語でコードブロックを記述したり、他のツールでハイライト表示や処理が可能なHTMLを生成したりすることが可能になります。

codelanguages = Python Rust Java Swift "C#"

QDocはC++ (Cpp)、QML、およびテキストを処理できるため、これらの言語はこのリストに指定する必要はありません。C#のように特殊文字を含む言語名は、このリストに含める際に二重引用符で囲む必要があります。

codelanguages 変数は、QDoc 6.11で導入され、オンラインのQtドキュメントにおいて、highlight.jsがサポートする言語の一部に対して構文強調表示を使用できるようにするものです。

関連項目 \code。

codeprefix、codesuffix

codeprefix およびcodesuffix 変数は、各コードスニペットを囲む文字列のペアを指定します。

定義

defines 変数は、QDoc が認識し、反応する C++ プリプロセッサシンボルを指定します。

defines 変数を使用してプリプロセッサシンボルを指定した場合、 \if コマンドを使用して、そのプリプロセッサシンボルが定義されている場合にのみ含まれるドキュメントを囲むこともできます。

defines = QT_GUI_LIB

これにより、QDoc はこれらのシンボルの定義を必要とするコードを確実に処理できるようになります。例：

#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endif

また、-D オプションを使用して、コマンドライン上でプリプロセッサシンボルを手動で定義することもできます。例えば：

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

この場合、-D オプションにより、qtgui.qdocconf ファイルで定義されたソースファイルを QDoc が処理する際に、qtforpython というプリプロセッサシンボルが確実に定義されるようになります。

「falsehoods」および \ifを参照してください。

依存関係

depends 変数は、型継承のリンク先や、ドキュメントがリンクする必要があるその他の項目を解決するために、このプロジェクトが依存する他のドキュメントプロジェクトのリストを定義します。

Qt自体と同様に、Qtのドキュメントも複数のモジュールに分散して配布されています。マルチモジュール型のドキュメントプロジェクトにおいて、単一のモジュールに必要な最小限の依存関係は、実際のビルド依存関係で構成されます。 さらに、ドキュメントセット全体の最上位のエントリポイントとして機能し、ナビゲーションリンクを提供するドキュメントプロジェクト（モジュール）がある場合、各モジュールのドキュメントはそれを依存関係として含める必要があります。

QDoc がプロジェクトのドキュメントを生成する際、プロジェクト内のリンク可能な各エンティティへの URL を含む `.index ` ファイルも生成されます。各依存関係は、プロジェクトの（小文字の）名前です。この名前は、そのプロジェクト用に生成されるインデックスファイルのベース名と一致している必要があります。

depends = \
    qtdoc \
    qtcore \
    qtquick

依存関係があり、depends 変数を使用するプロジェクトに対してQDocを実行する場合、コマンドラインオプションとして1つ以上の--indexdir パスを指定する必要があります。QDocはこれらのパスを使用して、依存関係のインデックスファイルを検索します。

qdoc mydoc.qdocconf --outputdir $PWD/html --indexdir $QT_INSTALL_DOCS

これにより、QDocはqtdoc への依存関係について、$QT_INSTALL_DOCS/qtdoc/qtdoc.index というファイルを検索します。依存関係のインデックスファイルが見つからない場合、QDocは警告を出力します。

depends コマンドは、特別な値「*」も受け付けます。これは、指定されたインデックスディレクトリ内にあるすべてのインデックスファイルをロードするよう QDoc に指示するものであり、つまり「すべてに依存する」ことを意味します。

depends = *

「indexes」、「project」、「url」も参照してください。

documentationinheaders

documentationinheaders = true を設定すると、C++ ベースのプロジェクトのドキュメントを生成する際、ヘッダーファイル内のドキュメントコメントも解析するよう QDoc に指示します。

この機能は、Qt 6.9 のリリースに伴い QDoc に導入されました。

exampledirs

exampledirs 変数は、サンプルファイルのソースコードが含まれるディレクトリを指定します。

examplesおよびexampledirs変数は、 \quotefromfile、 \quotefile および \example コマンドで使用されます。examples変数とexampledirs変数の両方が定義されている場合、QDoc はその両方を検索し、まずexamples、次にexampledirs の順に検索します。

QDocは指定された順序でディレクトリを検索し、最初に見つかった一致するファイルを採用します。検索は指定されたディレクトリ内のみで行われ、サブディレクトリ内は検索対象外となります。

exampledirs = $QTDIR/doc/src \
              $QTDIR/examples \
              $QTDIR \
              $QTDIR/qmake/examples

examples    = $QTDIR/examples/widgets/analogclock/analogclock.cpp

処理の際

\quotefromfile widgets/calculator/calculator.cpp

calculator.cpp QDocは、 examples 変数に「exampledirs 」という名前のファイルが値として指定されているか確認します。指定されていない場合、 変数内を検索し、まず「

$QTDIR/doc/src/widgets/calculator/calculator.cpp

存在しない場合、QDocは引き続き「xml-ph-0000@deepl.internal」という名前のファイルを探し続けます。

$QTDIR/examples/widgets/calculator/calculator.cpp

といった具合に、ファイルを探し続けます。

例も参照してください。

例

examples 変数を使用すると、 exampledirs 変数によって指定されたディレクトリにあるものに加えて、個別の例題ファイルを指定することができます。

examples および exampledirs 変数は、 \quotefromfile、 \quotefile および \example コマンドで使用されます。examples と exampledirs 変数が定義されている場合、QDocは両方を検索対象とし、まずexamples を、次に exampledirsの順に検索します。

QDocは、examples 変数にリストされている値を指定された順序で検索し、最初に見つかった値を採用します。

詳しい例については、 exampledirs コマンドを参照してください。ただし、ファイルがexamples 変数にリストされていることが分かっている場合は、そのパスを指定する必要はありません：

\quotefromfile calculator.cpp

exampledirs も参照してください。

examplesinstallpath

examplesinstallpath 変数は、インストールされた例題ディレクトリ内の、このプロジェクトの例題のルートパスを設定します。

すべてのサンプルについて、インストールルートパスがQT_INSTALL_EXAMPLES であると仮定すると、そのパスは

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

は、このドキュメント・プロジェクト内の個々の例へのパスを参照するために使用されます。これらのパスは、Qt Creator によって読み込まれる例のマニフェスト・ファイルに記録されています。

正しいパスを確保するには、examplesinstallpath がexampledirs にリストされているディレクトリのいずれかと一致している必要があります。各 \example コマンドの引数として渡されるパスは、exampledirs内のパスを基準とした相対パスとなります。

例：

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

そして、次のような\example コマンドが与えられた場合：

/*!
    \example basic/hello
    ...
*/

すると、この例では、mymodule/basic/hello というパスがマニフェストファイルに記録されます。

関連項目：exampledirs、 \example、および \meta。

examples.fileextensions

examples.fileextensions 変数は、ドキュメントに表示するための例題ファイルを収集する際、QDocが検索対象とするファイル拡張子を指定します。

デフォルトの拡張子は、*.cpp、*.h、*.js、*.xq、*.svg、*.xml、および *.ui です。

拡張子は標準的なワイルドカード式で指定されます。「+=」を使用して、フィルタにファイル拡張子を追加することができます。例：

examples.fileextensions += *.qrc

「headers.fileextensions」も参照してください。

examples.warnaboutmissingimages

例文ドキュメントの処理中、例文に画像が含まれていない場合、QDoc は警告を表示することがあります。この警告は、プロジェクトの .qdocconf ファイルで以下の設定変数を設定することで無効にできます:

examples.warnaboutmissingimages = false

この設定変数は、Qt 6.9 から QDoc に導入されました。

「examples.warnaboutmissingprojectfiles」も参照してください。

examples.warnaboutmissingprojectfiles

QDocは、サンプルドキュメントを処理する際、サンプルにプロジェクトファイルが含まれていない場合に警告を出力することがあります。この警告は、プロジェクトの.qdocconfファイルで以下の設定変数を設定することで無効にできます：

examples.warnaboutmissingprojectfiles = false

この設定変数は、Qt 6.9 から QDoc に導入されました。

examples.warnaboutmissingimages も参照してください。

excludedirs

excludedirs 変数は、sourcedirsやheaderdirs変数によって指定されたディレクトリに含まれている場合でも、QDocによる処理の対象外とするディレクトリを指定するためのものです。

例：

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

実行されると、QDocはリストされたディレクトリを以降の処理対象から除外します。これらのディレクトリ内のファイルは、QDocによって読み込まれません。

excludefiles も参照してください。

excludefiles

excludefiles 変数を使用すると、QDocによって処理されないようにすべき個々のファイルを指定することができます。

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

qtbase用のqdocconfファイルに上記を記述すると、QWidget に関するクラスドキュメントは生成されなくなります。

Qt 5.6 以降、excludefiles では単純なワイルドカード（「*」および「?」）も認識されるようになりました。たとえば、すべてのプライベートな Qt ヘッダーファイルの解析を除外するには、次のように定義します。

excludefiles += "*_p.h"

excludedirs も参照してください。

extraimages

extraimages 変数は、生成されるドキュメントに特定の画像を組み込むようQDocに指示します。

QDocは、 \image または \inlineimage コマンドで参照されている場合、QDocは自動的にその画像ファイルを`imagedirs`から出力ディレクトリにコピーします。追加の画像をコピーしたい場合は、extraimages 変数を使用してそれらを指定する必要があります。

一般的な構文は次のとおりです。 format.extraimages = imageです。

例：

HTML.extraimages = images/qt-logo.png

imagesおよびimagedirs も参照してください。

虚偽

falsehoods 変数は、指定されたプリプロセッサシンボルの真偽値を「false」として定義します。

この変数の値は正規表現です（詳細については「QRegularExpression 」を参照してください）。プリプロセッサ記号に対してこの変数が設定されていない場合、QDocはその真偽値を「true」とみなします。ただし、「0」は常に「false」となる例外です。

QDoc は、以下のプリプロセッサ構文を認識し、評価することができます。

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

ただし、次のような未知の構文に遭遇した場合は、

#if NOTYET
    ...
#endif

QDocは、falsehoods 変数のエントリ内でプリプロセッサシンボルが指定されていない限り、デフォルトでこれを真として評価します：

falsehoods = NOTYET

「defines」も参照してください。

generateindex

generateindex 変数には、HTMLドキュメントの生成時にインデックスファイルを生成するかどうかを指定するブール値が格納されます。

デフォルトでは、HTMLドキュメントの生成時に常にインデックスファイルが生成されるため、この変数は通常、この機能を無効にする場合（値をfalse に設定する場合）や、WebXML出力に対してインデックスの生成を有効にする場合（値をtrue に設定する場合）にのみ使用されます。

headerdirs

headerdirs 変数は、ドキュメントで使用される.cpp ソースファイルに関連付けられたヘッダーファイルが含まれるディレクトリを指定します。

headerdirs = $QTDIR/src \
             $QTDIR/extensions/activeqt \
             $QTDIR/extensions/motif \
             $QTDIR/tools/designer/src/lib/extension \
             $QTDIR/tools/designer/src/lib/sdk \
             $QTDIR/tools/designer/src/lib/uilib

実行されると、QDoc はまず最初に、 headers 変数で指定されたヘッダーファイル、およびheaderdir 変数で指定されたディレクトリ（すべてのサブディレクトリを含む）にあるヘッダーファイルを読み込み、クラスとその関数の内部構造を構築します。

次に、 sourcesで指定されたソースファイルと、 sourcedirs 変数で指定されたディレクトリ（すべてのサブディレクトリを含む）にあるソースを読み込み、そのドキュメントをヘッダーファイルから取得した構造と統合します。

headers とheaderdirs の両方の変数が定義されている場合、QDoc は両方を読み込みますが、まず headersheaderdirs の順に読み込みます。

指定されたディレクトリ内では、QDoc は、変数 `fileextensions ` で指定されたファイルのみを読み込みます headers.fileextensions 変数で指定されたファイルのみを読み込みます。 headers で指定されたファイルは、ファイル拡張子を考慮せずに読み込まれます。

「headers」および「headers.fileextensions」も参照してください。

headers

headers 変数を使用すると、 headerdirs 変数で指定されたディレクトリにあるものに加えて、個別のヘッダーファイルを指定できます。

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

headers 変数を処理する際、QDocの動作は headerdirs 変数を処理する場合と同様の動作をします。詳細については、 headerdirs 変数を参照してください。

headerdirs も参照してください。

headers.fileextensions

headers.fileextensions 変数は、ヘッダーで使用される拡張子を指定します。

xml-ph-0000@deepl.internal変数で指定されたヘッダーファイルを処理する際、 headerdirs 変数で指定されたヘッダーファイルを処理する際、QDocはheaders.fileextensions 変数で指定されたファイル拡張子を持つファイルのみを読み込みます。これにより、QDocは不要なファイルを読み込む時間を省くことができます。

デフォルトの拡張子は、*.ch、*.h、*.h++、*.hh、*.hpp、および *.hxx です。

拡張子は標準的なワイルドカード式で指定されます。「+=」を使用することで、フィルタにファイル拡張子を追加することができます。例：

header.fileextensions += *.H

headerdirs も参照してください。

includepaths

includepaths 変数は、QDocがドキュメントコメントの解析のためにC++コードを解析する際に使用するClangパーサーへ、追加のインクルードパスを渡すために使用されます。

この変数には、-I （インクルードパス）、-F （macOS フレームワークのインクルードパス）、または-isystem （システムのインクルードパス）という接頭辞が付いたパスのリストを指定できます。接頭辞が省略された場合、デフォルトでは-I が使用されます。

現在の .qdocconf ファイルを基準とした相対パスは、絶対パスに変換されます。ファイルシステム上に存在しないパスは無視されます。

「moduleheader」も参照してください。

includeprivate

includeprivate を使用すると、ドキュメントに C++ クラスのプライベートメンバーを含めることができます。QDoc は通常、生成されるドキュメントからプライベート関数、型、および変数を除外します。

すべてのプライベートメンバーを含めるには、includeprivate をtrue に設定します：

includeprivate = true

特定のメンバ型のみを有効にすることもできます:

# Include only private functions
includeprivate.functions = true

# Include only private types (classes, enums, typedefs)
includeprivate.types = true

# Include only private variables
includeprivate.variables = true

個別の設定はグローバル設定よりも優先されます。例えば：

includeprivate = true
includeprivate.types = false

この設定には、プライベート関数および変数が含まれますが、プライベート型は除外されます。

QDocは、Qt 6.11でincludeprivate を導入しました。

internalfilepatterns

internalfilepatterns 変数は、内部実装ファイルを識別するファイルパスパターンを指定します。これらのパターンに一致するファイル内で宣言されたクラスは、そのすべてのメンバー（プロパティ、関数、列挙型、ネストされた型）とともに、自動的に「Internal」としてマークされます。ファイルスコープにあるフリー関数、列挙型、およびtypedefは、この設定の影響を受けません。

showinternalがfalse （デフォルト）の場合、これらのエンティティはドキュメントの検証対象から除外されます。showinternal がtrue の場合、これらはドキュメントに含まれますが、「Internal」ステータスは維持されるため、ジェネレータはこれらに対して異なるスタイルを適用することができます（内部APIに対する視覚的な識別子の追加など）。

これは、ドキュメント化されたパブリックインターフェースの一部ではないクラスを含むプライベート実装ヘッダーに有用です。Qt では、これには_p.h で終わるプライベートヘッダーが含まれます。

パターンの構文

パターンには、次の2つの構文がサポートされています：

• シェル形式のグロブパターン：* が任意の文字に、? がちょうど 1 文字に一致する、単純なワイルドカードです。グロブパターンはフルパスではなくファイル名のみと照合されるため、*_p.h のようなパターンに最適です。
• 正規表現：パスベースのマッチングを行うには、正規表現の構文を使用します。正規表現のメタ文字（^$[]{}()|+\\. ）を含むパターンはすべて正規表現として扱われ、正規化された完全なファイルパスに対してマッチングが行われます。

パターンのマッチングでは、ディレクトリ区切り文字としてスラッシュ（/ ）が使用されます。QDocは内部でパス区切り文字を正規化するため、プラットフォームに関係なく、パターン内では常に/ を使用してください。

ファイルの場所によりクラスが「Internal」としてマークされている場合、その「Internal」ステータスはノード階層を通じてそのすべてのメンバーに自動的に伝播されます。

例 - Qt 規約 (glob):

internalfilepatterns = *_p.h

任意のディレクトリ階層において、_p.h で終わるすべてのファイルに一致します。

例 - 複数のファイル名パターン (glob):

internalfilepatterns = *_p.h *_impl.h *_pch.h

_p.h 、_impl.h 、または_pch.h で終わるファイルに一致します。

例 - ディレクトリベースのマッチング（正規表現）：

internalfilepatterns = .*/internal/.*\.h

任意のinternal ディレクトリ内の、任意の深さにある.h ファイルに一致します。

例 - 複数のパターン:

internalfilepatterns = *_p.h .*/private/.*\.h

単純なケースではグロブパターンを、複雑なパスでは正規表現を組み合わせて使用します。

QDocは、Qt 6.11でinternalfilepatterns を導入しました。

関連項目： excludedirsおよびexcludefiles。

ignorewords

ignorewords 変数は、QDocがハイパーリンクのターゲットを解決する際に無視する文字列のリストを指定するために使用されます。

QDoc には自動リンク機能があり、C++ や QML のエンティティに類似した単語に対してリンクの生成が試みられます。具体的には、文字列の長さが 3 文字以上で、空白を含まず、かつ

• キャメルケースの単語であること（つまり、インデックスが0より大きい位置に少なくとも1つの大文字が含まれていること）、または
• 「() 」または「:: 」という部分文字列を含むか、
• @ または_ といった特殊文字を少なくとも1つ含んでいる場合です。

ignorewords に修飾語を追加すると、QDoc によるその単語への自動リンクが停止します。たとえば、単語「OpenGL」が有効なリンク先（セクション、 \page、または \externalpage タイトル）である場合、各出現箇所でのハイパーリンクを回避するには、次のように記述します。

ignorewords += OpenGL

明示的に \l は、無視される単語に対しても引き続き機能します。

ignorewords 変数は、QDoc 5.14で導入されました。

ignoresince

ignoresince 変数は、 \since コマンドに渡されるバージョンのカットオフ値を設定するために使用されます。カットオフ値より低いバージョンを定義するすべての\since コマンドは無視され、出力は生成されません。

このカットオフ値はプロジェクトごとに異なります。プロジェクト名はサブ変数として定義できます。デフォルトのプロジェクト名はQt です。例：

ignoresince      = 5.0
ignoresince.QDoc = 5.0

これにより、メジャーバージョンが 4 以下で、プロジェクトが `QDoc ` または未定義である `\since ` コマンドは無視されます。

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

ignoresince 変数は、QDoc 5.15で導入されました。

関連項目 \since.

imagedirs

imagedirs 変数は、ドキュメントで使用される画像が含まれているディレクトリを指定します。

images およびimagedirs 変数は、 \image および \inlineimage コマンドで使用されます。 images とimagedirs の両方の変数が定義されている場合、QDocは両方を検索対象とします。まず images、次にimagedirs の順で検索します。

QDocは指定された順序でディレクトリを検索し、最初に見つかった一致するファイルを採用します。検索は指定されたディレクトリ内のみで行われ、サブディレクトリ内は検索対象外となります。

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

処理の際、

\image calculator-example.png

処理の際、QDocはimages 変数の値として「calculator-example.png」というファイル名が指定されているかどうかを確認します。指定されていない場合、imagedirs 変数内で以下を検索します：

$QTDIR/doc/src/images/calculator-example.png

ファイルが存在しない場合、QDocは

$QTDIR/examples/calculator-example.png

imagesoutputdirという名前のファイルを探します

imagesoutputdir 変数は、出力ディレクトリの下にQDocが画像を保存するために使用するサブディレクトリの名前を指定します。

imagesoutputdir のデフォルト値は「images」です。

引数として渡された画像ファイルは \image および \inlineimage コマンドの引数として渡された画像ファイルは、このディレクトリにコピーされます。

画像用のカスタム出力ディレクトリを設定することは、複数のドキュメントプロジェクトが共有の出力ディレクトリを使用するように構成されている、マルチモジュールのドキュメントビルドにおいて有用です。たとえば、次のような（共有の）設定の場合：

imagesoutputdir = images/${project}

ビルド内の各ドキュメントプロジェクトは、<outputdir>/images/<project name> を使用して画像を保存するため、同名の画像ファイルが互いに上書きし合うことを回避できます。

この変数は、Qt 6.11 で QDoc に導入されました。

言語

language 変数は、ドキュメントで使用されるソースコードの言語を指定します。具体的には、\code..\endcode ブロック内のソースコードを解析する際のデフォルト言語を定義します。

language = Cpp

デフォルトの言語は C++ (Cpp) であり、明示的に指定する必要はありません。ドキュメント内のコードスニペットが主に QML コードで構成されている場合は、デフォルトを QML に設定してください:

language = QML

関連項目 \code。

locationinfo

locationinfo というブール変数は、各エンティティに関する詳細な位置情報が、.index ファイルおよび.webxml ファイル（WebXML出力形式を使用する場合）に書き込まれるかどうかを決定します。

位置情報は、ソースコード内の宣言またはドキュメントコメントブロックのフルパスと行番号で構成されます。

これをfalse に設定すると、位置情報は無効になります：

locationinfo = false

デフォルト値はtrue です。

locationinfo 変数は、QDoc 5.15 で導入されました。

logwarnings

logwarnings ブール変数は、QDoc が stderr に加えてログファイルにも警告メッセージを書き出すかどうかを決定します。

true に設定すると、QDoc は出力ディレクトリに<project>-qdoc-warnings.log という名前のログファイルを作成し、すべての警告メッセージをこのファイルに書き込みます。警告は、通常どおり stderr にも引き続き書き込まれます。

ログファイルには、プロジェクト情報を含むヘッダーと、再現性を確保するためにQDocの起動に使用されたコマンドライン引数がデフォルトで含まれます。

これをtrue に設定すると、警告のロギングが有効になります：

logwarnings = true

デフォルト値は `false` です。

この機能は、ドキュメントの量が多い場合や、警告が大量に発生し、スクロールが速すぎて体系的に分析できないCI環境などで役立ちます。

logwarnings 変数は、QDoc 6.11で導入されました。

logwarnings.disablecliargs

logwarnings.disablecliargs というブール型のサブ変数は、警告ログファイルのヘッダーからCLI引数を省略するかどうかを制御します。

logwarnings.disablecliargs = true

true に設定すると、ログファイルのヘッダーからコマンドライン引数が省略されるため、異なる環境間でもログファイルを互換性を持たせることができます。これは、コマンドライン引数に環境固有のパスや一時ディレクトリが含まれるテストスイートやCIシステムで有用です。

デフォルト値は `false` です。変数 `logwarnings.disablecliargs ` は QDoc 6.11 で導入されました。

マクロ

macro 変数は、独自のシンプルなQDocコマンドを作成するために使用されます。構文は macro.command = definitionです。command は文字と数字の組み合わせに限定されますが、ダッシュやアンダースコアなどの特殊文字は使用できません。definition はQDoc 構文を使用して記述します。

マクロ変数の使用を、特定の出力形式に限定することができます。例えば、マクロ名に `.HTML ` を付加することで、そのマクロは HTML 出力を生成する場合にのみ使用されます。

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

最初のマクロは、引数を太字で表示する `\key ` コマンドを定義しています。2番目のマクロは、上付きのアスタリスクを表示する `\raisedaster ` コマンドを定義していますが、これはHTMLを生成する場合にのみ使用されます。

また、マクロは最大7つのパラメータを受け取ることができます：

macro.hello            = "Hello \1!"

パラメータは、他のコマンドと同様にマクロに渡されます：

\hello World

複数のパラメータを使用する場合、または引数に空白が含まれる場合は、各引数を中括弧で囲んでください：

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

展開されたマクロに対して追加の正規表現パターンマッチングを行うために、特別なマクロオプション「match」を追加することができます。

たとえば、

macro.qtminorversion       = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"

これにより、環境変数 QT_VER に基づいてマイナーバージョンに展開されるマクロ `\qtminorversion ` が作成されます。

マッチパターンを定義するマクロは、すべてのキャプチャグループ（括弧）を連結して出力します。また、パターンにキャプチャグループが含まれていない場合は、完全に一致した文字列を出力します。

定義済みのマクロの詳細については、「マクロ」を参照してください。

manifestmeta

manifestmeta 変数は、QDocによって生成されるサンプルマニフェストファイルに対する追加のメタコンテンツを指定します。

詳細については、「マニフェストのメタコンテンツ」のセクションを参照してください。

moduleheader

moduleheader 変数は、ドキュメント化されたC++モジュールのモジュールヘッダー名を定義します。

C++ API をドキュメント化するプロジェクトでは、そのモジュールのすべてのパブリッククラス、名前空間、およびヘッダーファイルを含むモジュールレベルのヘッダーが必要です。QDoc の Clang パーサーは、このファイルを使用してモジュールのプリコンパイル済みヘッダー (PCH) を生成し、ソースファイルの解析速度を向上させます。

デフォルトでは、プロジェクト名がモジュールヘッダー名としても使用されます。

project = QtCore

上記のプロジェクト名の場合、QDocはすべての既知のインクルードパスからモジュールヘッダー「QtCore」を検索します。まずコマンドライン引数として渡されたパスを使用し、次に`includepaths`変数にリストされているパスを順に検索します。

モジュールヘッダーが見つからない場合、QDocは警告を出します。その後、headerdirs変数にリストされているヘッダーに基づいて、人工的なモジュールヘッダーの生成を試みます。

Qtドキュメントプロジェクトの場合、project 変数が正しく設定されていれば、通常、ビルドシステムはモジュールヘッダーを見つけるための正しいインクルードパスをQDocに提供します。moduleheader 変数は、QDocが検索するための代替ファイル名を指定します。

C++ ドキュメントを含まないプロジェクトの場合は、 parsecppcomments 変数を使用して、C++の解析を無効にします。moduleheader を空の文字列に設定しても同様の効果があり、下位互換性のためにサポートされています：

# No C++ code to document in this project
moduleheader =

関連項目 parsecppcomments、includepaths、およびproject を参照してください。

自然言語

naturallanguage 変数は、QDocによって生成されるドキュメントに使用される自然言語を指定します。

naturallanguage = zh-Hans

デフォルトでは、レガシードキュメントとの互換性を確保するため、自然言語はen に設定されています。

QDocは、lang およびxml:lang 属性を使用して、生成するHTMLに自然言語情報を追加します。

「sourceencoding」、「outputencoding」、C.7. 「lang および xml:lang 属性」、およびベストプラクティス 13: 「Hans および Hant コードの使用」も参照してください。

ナビゲーション

navigation のサブ変数が定義されている場合、各ページで生成されるナビゲーションバーに表示されるホームページ、ランディングページ、C++クラスページ、およびQMLタイプページが設定されます。

複数のサブプロジェクト（たとえば、Qtモジュール）を含むプロジェクトでは、通常、各サブプロジェクトが独自のランディングページを定義しますが、すべてのサブプロジェクトで同じホームページが使用されます。

サブ変数

例：

# Common configuration
navigation.homepage  = index.html
navigation.hometitle = "Qt $QT_VER"

# qtquick.qdocconf
navigation.landingpage    = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage   = "Qt Quick QML Types"

上記の設定により、Item QML タイプに対して次のようなナビゲーションバーが生成されます：

Qt 5.10 > Qt Quick > QML Types > Item QML Type

目次とナビゲーションリンク

目次（TOC）として機能するページが1つ以上ある場合は、それらのタイトルをnavigation.toctitles にリストアップすることで、目次に記載されたすべてのページに対するナビゲーションリンク（前のページ・次のページ）の生成を自動化できます。

QDocでは、 \list リンクを各目次ページに期待しています。ネストされたサブリストも許可されています。

たとえば、

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
        \list
            \li \l {What's new in v1.3} {v1.3}
            \li \l {What's new in v1.2} {v1.2}
            \li \l {What's new in v1.1} {v1.1}
        \endlist
\endlist

QDoc バージョン 6.10 以降では、 \generatelist 目次リストに以下のように表示されることもあります：

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
    \generatelist [descending] whatsnew
\endlist

ここでは、3つの「新機能」ページすべてが同じwhatsnew グループに属していると仮定した場合、結果は最初の\list と同様になります。

関連項目 \ingroup。

overloadedsignalstarget

デフォルト: connecting-overloaded-signals

overloadedsignalstarget 変数は、オーバーロードされたシグナルの自動生成ノートで使用されるリンク先を指定します。

QDocがオーバーロードされたシグナルを検出すると、オーバーロードされたシグナルへの接続方法に関するヘルプドキュメントへのリンクを含む注釈を生成します。デフォルトでは、このリンクはconnecting-overloaded-signals という名前のターゲットを参照します。

プロジェクトでは、これをカスタマイズして独自のドキュメントへリンクさせることができます:

# Link to a target within the project
overloadedsignalstarget = signals-guide.html#overloaded-signals

# Link to external documentation
overloadedsignalstarget = https://example.com/docs/signals.html#overloaded-signals

ターゲットは以下の通りです：

• 単純なターゲット名（ \target コマンド）:connecting-overloaded-signals
• 相対URL：signals-guide.html#overloaded-signals
• 絶対URL：https://example.com/docs/signals.html#overloaded-signals

overloadedslotstargetも参照してください。

overloadedslotstarget

デフォルト: connecting-overloaded-slots

overloadedslotstarget 変数は、オーバーロードされたスロットについて自動的に生成される注釈で使用されるリンク先を指定します。

QDocはオーバーロードされたスロットを検出すると、そのスロットへの接続方法に関するヘルプドキュメントへのリンクを含む注釈を生成します。デフォルトでは、このリンクは「connecting-overloaded-slots 」という名前のターゲットを指します。

プロジェクトでは、これをカスタマイズして独自のドキュメントにリンクさせることができます：

# Link to a target within the project
overloadedslotstarget = signals-guide.html#overloaded-slots

# Link to external documentation
overloadedslotstarget = https://example.com/docs/slots.html#overloaded-slots

ターゲットは以下のようになります：

• 単純なターゲット名（ \target コマンド）:connecting-overloaded-slots
• 相対URL：signals-guide.html#overloaded-slots
• 絶対URL:https://example.com/docs/slots.html#overloaded-slots

overloadedsignalstargetも参照してください。

outputdir

outputdir 変数は、QDocが生成したドキュメントを保存するディレクトリを指定します。

outputdir = $QTDIR/doc/html

生成されたQtリファレンスドキュメントは、$QTDIR/doc/htmlに配置されます。たとえば、QWidget クラスのドキュメントは

$QTDIR/doc/html/qwidget.html

関連する画像は、images サブディレクトリに配置されます。

outputencoding

outputencoding 変数は、QDocによって生成されるドキュメントに使用されるエンコーディングを指定します。

outputencoding = UTF-8

デフォルトでは、レガシードキュメントとの互換性を確保するため、出力エンコーディングはISO-8859-1 （Latin1）に設定されています。一部の言語、特に非ヨーロッパ言語のドキュメントを生成する場合、これでは不十分であり、UTF-8などのエンコーディングが必要となります。

QDocはこのエンコーディングを使用してHTMLをエンコードし、使用されているエンコーディングをブラウザに通知するための適切な宣言を生成します。また、ブラウザに完全な文字エンコーディングおよび言語情報を提供するために、naturallanguage設定変数も指定する必要があります。

「outputencoding」および「naturallanguage」も参照してください。

outputformats

outputformats 変数は、生成されるドキュメントの形式を指定します。

Qt 5.11 以降、QDoc は HTML および WebXML 形式をサポートしており、Qt 5.15 以降では DocBook 形式でのドキュメント生成も可能になりました。outputformats が指定されていない場合、QDoc は HTML 形式（デフォルト形式）でドキュメントを生成します。 すべての出力形式について、専用の出力ディレクトリやその他の設定を指定することができます。例：

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

これにより、デフォルト設定でHTMLドキュメントが生成されるほか、出力サブディレクトリ「webxml」にWebXMLドキュメントも生成されます。

outputprefixes

outputprefixes 変数は、ファイルの種類と、生成されたドキュメント内の出力ファイル名の先頭に付加されるプレフィックスとの対応関係を指定します。

QDocでは、QML型、C++クラス、名前空間、およびヘッダーファイルのリファレンスページについて、ファイル名に出力プレフィックスを追加する機能をサポートしています。

outputprefixes     = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-

デフォルトでは、QML 型の API ドキュメントを含むファイルには「qml- 」というプレフィックスが付きます。上記の例では、代わりに「uicomponents- 」というプレフィックスが使用されています。

同様に、上記の例では、C++ 型のドキュメントページにはcomponents- というプレフィックスが付いています。デフォルトでは、C++ 型のページにはプレフィックスは付きません。

outputsuffixes

outputsuffixes 変数は、ファイルの種類と、出力ファイル名に表示されるモジュール名または型名に付加される拡張子との対応関係を指定します。

QDocでは、モジュールページ、QML型、C++クラス、名前空間、およびヘッダーファイルのリファレンスページのファイル名に出力サフィックスを追加することができます。

デフォルトでは、サフィックスは使用されません。QML 出力サフィックスが定義されている場合、QML 型および QML モジュールページのファイル名に表示されるモジュール名に対して、そのサフィックスが適用されます。

C++ 型のファイル名にはモジュール名は含まれません。CPP 出力サフィックスが定義されている場合、それは型名のサフィックスとして適用されます。

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

上記の定義に基づき、QMLモジュール名がFooBarで、デフォルトの出力プレフィックスが（qml- ）の場合、QML型FooWidgetの生成ファイル名はqml-foobar-tp-foowidget.html となります。

同様に、C++ クラスQFoobar の場合、QDoc はqfoobar-tp.html を生成します。

outputsuffixes 変数は、QDoc 5.6 で導入されました。

parsecppcomments

parsecppcomments 変数は、QDocがClangベースのC++パーサーを使用してC++ソースファイルを解析するかどうかを制御します。

false に設定すると、QDocはそのプロジェクトに対してClangによる解析とPCH生成をスキップし、代わりに純粋なドキュメントパーサーを使用して.cpp ファイルを処理します。これは、QML APIのみをドキュメント化するプロジェクトで、C++ソースファイルにQDocコメントは含まれているものの、ドキュメント化するべきC++エンティティが存在しない場合に役立ちます。

デフォルト値はtrue です。

parsecppcomments = false

parsecppcomments 変数は、Qt 6.12 で QDoc に導入されました。

関連項目 moduleheader。

qhp

qhp のサブ変数は、Qt Help Project（qhp ）ファイルに出力される情報を定義するために使用されます。

このプロセスに関する詳細については、「ヘルププロジェクトファイルの作成」の章を参照してください。

QDoc 6.6 以降、qhp 変数のベース値をtrue に設定すると、有効なヘルププロジェクト構成が期待されることを意味します：

qhp = true

これにより、プロジェクト設定でqhp.projects が定義されていない場合、QDocは警告を出力します。これは、Qtのようにトップレベルの.qdocconfファイルを共有するすべてのドキュメントプロジェクトが正しく設定されていることを確認するのに役立ちます。

この警告を無効にするには、変数をfalse に設定してください。

showautogenerateddocs

ブール変数 `showautogenerateddocs ` は、明示的にデフォルト値が設定された特殊メンバー関数や削除された特殊メンバー関数に対して QDoc が自動的に生成するドキュメントを出力に含めるかどうかを決定します。

QDocは、そのような関数に対する \fn ブロックでそのような関数が記述されていない場合に生成します。 \fn で記述されたドキュメントは、生成されたテキストよりも常に優先され、この変数の影響を受けません。

これをfalse に設定すると、自動生成されたドキュメントは省略されます：

showautogenerateddocs = false

デフォルト値は `true` です。

showautogenerateddocs 変数は QDoc 6.12 で導入されました。

sourcedirs

sourcedirs 変数は、ドキュメントで使用される.cpp または.qdoc ファイルが含まれるディレクトリを指定します。

sourcedirs  += .. \
               ../../../examples/gui/doc/src

実行されると、QDoc はまず、 header 変数で指定されたヘッダーファイル、およびheaderdir 変数で指定されたディレクトリ（すべてのサブディレクトリを含む）にあるヘッダーファイルを読み込み、クラスとその関数の内部構造を構築します。

次に、 sourcesで指定されたソースファイル、および sourcedirs 変数で指定されたディレクトリ（すべてのサブディレクトリを含む）にあるソースを読み込み、ドキュメントをヘッダーファイルから取得した構造と統合します。

sources とsourcedirs の両方の変数が定義されている場合、QDoc は両方を読み込み、まず sourcessourcedirs の順に読み込みます。

指定されたディレクトリ内では、QDocは変数fileextensions で指定されたファイルのみを読み込みます sources.fileextensions で指定されたファイルのみを読み込みます。 sources で指定されたファイルは、ファイル拡張子に関係なく読み込まれます。

「sources」および「sources.fileextensions」も参照してください。

sourceencoding

sourceencoding 変数は、ソースコードおよびドキュメントに使用されるエンコーディングを指定します。

sourceencoding = UTF-8

デフォルトでは、レガシーのドキュメントとの互換性を確保するため、ソースのエンコーディングはISO-8859-1 (Latin1) になっています。一部の言語、特に非ヨーロッパ言語では、これだけでは不十分であり、UTF-8などのエンコーディングが必要となります。

QDocはこのエンコーディングを使用してソースファイルやドキュメントファイルを読み込みますが、C++コンパイラの制限により、ソースコードのコメントで非ASCII文字を使用できない場合があります。このような場合、APIドキュメントをすべてドキュメントファイル内に記述することが可能です。

「naturallanguage」および「outputencoding」も参照してください。

ソース

sources 変数を使用すると、sourcedirs変数で指定されたディレクトリにあるファイルに加えて、個別のソースファイルを指定することができます。

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

sources 変数の処理において、QDocはsourcedirs変数の処理時と同様の動作を行います。詳細については、sourcedirs変数を参照してください。

sourcedirs も参照してください。

sources.fileextensions

sources.fileextensions 変数は、ソースディレクトリ内のファイルをフィルタリングします。

xml-ph-0000@deepl.internal変数で指定されたソースファイルを処理する際、 sourcedirs 変数で指定されたソースファイルを処理する際、QDocはsources.fileextensions 変数で指定されたファイル拡張子を持つファイルのみを読み込みます。これにより、QDocは関係のないファイルを読み込む時間を節約します。

デフォルトの拡張子は、*.c++、*.cc、*.cpp、*.cxx、*.mm、*.qml、および*.qdocです。

拡張子は標準的なワイルドカード式で指定されます。「+=」を使用して、フィルタにファイル拡張子を追加することができます。例：

sources.fileextensions += *.CC

sourcedirsおよびsources も参照してください。

spurious

spurious 変数は、指定されたQDoc警告を出力から除外します。警告は、標準のワイルドカード式を使用して指定します。

spurious = "Cannot find .*" \
"Missing .*"

これにより、これらの式のいずれかに一致する警告は、QDocの実行時に出力に含まれなくなります。たとえば、次のような警告は出力から除外されるでしょうか：

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

syntaxhighlighting 変数は、QDocが生成するドキュメント内で引用されたソースコードに対して、QDocが構文強調表示を行うかどうかを指定します。

syntaxhighlighting = true

とすると、サポートされているすべてのプログラミング言語で構文強調表示が有効になります。

tabsize

tabsize 変数は、タブ文字のサイズを定義します。

tabsize = 4

と設定すると、タブ文字のサイズは4スペースになります。この変数のデフォルト値は8であり、明示的に指定する必要はありません。

tagfile

tagfile 変数は、HTML生成時に書き出されるDoxygenタグファイルを指定します。

version

version 変数は、ドキュメント化されるソフトウェアのバージョン番号を指定します。

version = 5.6.0

バージョン番号が指定された場合（ version または versionsym.qdocconf ）でバージョン番号が指定されると、ドキュメント内で使用するために、対応する\version コマンドを通じてそのバージョン番号にアクセスできます。

「versionsym」も参照してください。

versionsym

versionsym 変数は、ドキュメント化されたソフトウェアのバージョン番号を定義するC++プリプロセッサシンボルを指定します。

versionsym = QT_VERSION_STR

QT_VERSION_STR は、qglobal.h において次のように定義されています

#define QT_VERSION_STR   "5.14.1"

バージョン番号が指定された場合（ version または versionsym.qdocconf 変数を使用して指定された場合）、ドキュメント内で使用するために、対応する\version コマンドを通じてアクセス可能です。

関連項目 \version。

warninglimit

warninglimit 変数は、許容されるドキュメント警告の最大数を設定します。この制限を超えた場合、QDocは通常通り処理を続行しますが、警告数をエラーコードとして指定して終了します。制限を超えていない場合、またはwarninglimit が定義されていない場合、QDocプロセスは、他に重大なエラーがないことを前提として、0を返して終了します。

warninglimit を0 に設定すると、警告が1つでも発生した時点で処理は失敗となります。

たとえば、

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

warninglimit 変数は Qt 5.11 で導入されました。