これらのコマンドは、ドキュメントの見た目やドキュメント生成のプロセスに関連する各種機能を提供します。

\annotatedlist

\annotatedlist コマンドを実行すると、グループのメンバー一覧が表示され、各メンバーにはその概要テキストが付きます。以下は、Qtリファレンスドキュメントからの例です：

/*!
   ...
   \section1 Drag and Drop Classes

   These classes deal with drag and drop and the necessary mime type
   encoding and decoding.

   \annotatedlist draganddrop
*/

\ingroup これにより、 draganddropグループに含まれるすべての C++ クラスおよび/または QML 型のリストが生成されます。draganddropグループ内の C++ クラスまたは QML 型は、その\class または \qmltype に「xml-ph-0000@deepl.internal draganddrop」という記述が含まれています。

グループのメンバーは、ユーザーに表示される名前またはタイトルに基づいて昇順で並べ替えられます。QDoc 6.8 以降では、\annotatedlist および \generatelist supportもカスタムソートをサポートしています。

関連項目 \generatelist および「グループメンバーの並べ替え」も参照してください。

\cmakepackage

\cmakepackage コマンドを使用して、クラスや名前空間にCMakeパッケージ情報を追加します。この情報は、クラスまたは名前空間のドキュメントページの上部に表示される表に反映されます。例：

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakepackage Baz
    \brief A namespace.

    ...
*/

QDocはこれを次のように出力します。

Foo ネームスペース

A ネームスペース。詳細...

ヘッダー:	#include <Bar>
CMake:	find_package(Baz REQUIRED) target_link_libraries(mytarget PRIVATE Baz::Baz)

関連項目\module および \cmakecomponent}

\cmakecomponent

\cmakecomponent コマンドを使用すると、クラスや名前空間にCMakeコンポーネント情報を追加できます。この情報は、クラスまたは名前空間のドキュメントページの上部にある表に表示されます。例：

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \brief A namespace.

    ...
*/

QDocはこれを次のように出力します。

Foo ネームスペース

名前空間。詳細...

ヘッダー:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::Baz)

関連項目\module および \cmakepackage}

\cmaketargetitem

\cmaketargetitem コマンドを使用すると、クラスや名前空間に追加されるCMakeのtarget_link_libraries 情報のうち、アイテム部分を上書きできます。このコマンドは、 \module および \cmakecomponent コマンドと組み合わせて使用する必要があります。例：

/*!
    \namespace Foo
    \inheaderfile Bar
    \cmakecomponent Baz
    \cmaketargetitem Qt6::BazPrivate
    \brief A namespace.

    ...
*/

QDocはこれを次のように出力します。

Foo 名前空間

名前空間。詳細...

ヘッダー:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz) target_link_libraries(mytarget PRIVATE Qt6::BazPrivate)

関連項目\module および \cmakecomponent}

\qtcmakepackage

\qtcmakepackage コマンドを使用すると、クラスや名前空間にCMakeパッケージ情報を追加できます。この情報は、クラスまたは名前空間のドキュメントページの上部に表示される表に反映されます。例：

/*!
    \namespace Foo
    \inheaderfile Bar
    \qtcmakepackage Baz
    \brief A namespace.

    ...
*/

QDocはこれを次のように出力します。

Foo ネームスペース

名前空間。詳細...

ヘッダー:	#include <Bar>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Baz)

\qtcmaketargetitem

\qtcmaketargetitem コマンドを使用すると、クラスや名前空間に追加されるCMakeのtarget_link_libraries 情報のうち、item部分を上書きできます。このコマンドは、 \module および \qtcmakepackage コマンドと組み合わせて使用する必要があります。

関連項目\module および \qtcmakepackage}

\generatelist

\generatelist コマンドは、 \ingroup コマンドでグループ化されたドキュメントエンティティ、または以下に挙げる引数のいずれかに一致するエンティティへのリンクのリストに展開されます。Qtリファレンスドキュメントからの例：

/*!
   \page classes.html
   \title All Classes

   For a shorter list that only includes the most
   frequently used classes, see \l{Qt's Main Classes}.

   \generatelist classes Q
*/

これにより、「すべてのクラス」ページが表示されます。このコマンドは、以下の引数を受け付けます:

<group-name>

引数としてグループ名のみを指定すると、QDocは\ingroup <group-name> コマンドを使用しているすべてのエンティティを一覧表示します。

グループメンバーの並べ替え

グループメンバーのリストを生成する際、メンバーはユーザーに表示される名前またはタイトルに基づいて昇順で並べ替えられます。QDoc 6.8 以降、デフォルトの並べ替え順序を変更できるようになりました：

\generatelist [descending] changelogs

「changelogs」グループが、各バージョンの変更点を詳述したページで構成されていると仮定すると、これによりリストは降順（最新バージョンが先頭）で生成されます。

ソートキー

QDoc 6.8 以降、 \meta コマンドを使用して、1つ以上のグループメンバーにカスタムソートキーを割り当てることができます：

\meta sortkey {sort key}

これにより、ユーザーに表示されるタイトルではなく、これらのキーに基づいて（昇順または降順で）ソートが行われます。

annotatedclasses

annotatedclasses 引数は、すべてのクラスの名前と、各クラスの説明を含むテーブルを提供します。各クラス名は、そのクラスのリファレンスドキュメントへのリンクとなっています。例：

C++ クラスは、 \class コマンドで文書化されます。クラスの注釈は、クラスコメントの \brief コマンドの引数から取得されます。

annotatedexamples

annotatedexamples 引数は、すべての例のタイトルと各例の説明を含む一連の表として、すべての例の完全なリストを提供します。各タイトルは、その例のドキュメントへのリンクとなっています。

（ドキュメント化された例がある）各モジュールについて、そのモジュールに `navigation.landingpage` 設定変数が定義されている場合に限り、個別の表が生成されます。`landingpage` 変数は、各表の先頭に表示されるヘッダーのタイトルとして使用されます。

annotatedattributions

annotatedattributions 引数は、すべての帰属情報の完全なリストを、すべての帰属情報のタイトルと各帰属情報の説明を含む一連の表として提供します。各タイトルは、その帰属情報のページへのリンクとなっています。

モジュールが `navigation.landingpage` 設定変数を定義している場合、各モジュール（アトリビューションを持つもの）ごとに個別のテーブルが生成されます。`landingpage` 変数は、各テーブルの前に配置されるヘッダーのタイトルとして使用されます。

classes <prefix>

classes 引数は、クラスの完全なアルファベット順リストを提供します。 2番目の引数 `<prefix>` は、クラス名の共通プレフィックスです。クラス名は、共通プレフィックスの後に続く文字に基づいてソートされます。例：Qtクラスの共通プレフィックスは `Q` です。共通プレフィックス引数はオプションです。共通プレフィックスが指定されていない場合、クラス名は最初の文字に基づいてソートされます。

各クラス名は、そのクラスのリファレンスドキュメントへのリンクになります。このコマンドは、次のようにして「すべてのクラス」ページを生成するために使用されます:

/*!
    \page classes.html
    \title All Classes
    \ingroup classlists

    \brief Alphabetical list of classes.

    This is a list of all Qt classes. For classes that
    have been deprecated, see the \l{Obsolete Classes}
    list.

    \generatelist classes Q
*/

C++クラスのドキュメントは、 \class コマンドでドキュメント化されます。

classesbymodule

この引数を使用する場合、2番目の引数が必須となり、そこにはリストするクラスが含まれるモジュールを指定します。QDocは、それらのクラスを含むテーブルを生成します。各クラスは、その \brief コマンドのテキストと共に一覧表示されます。

たとえば、このコマンドはモジュールページで次のように使用できます：

/*!
    \page phonon-module.html
    \module Phonon
    \title Phonon Module
    \ingroup modules

    \brief Contains namespaces and classes for multimedia functionality.

    \generatelist{classesbymodule Phonon}

    ...
*/

指定されたモジュールに属する各クラスは、 \inmodule\class コメント内でこのコマンドでマークする必要があります。

qmltypesbymodule

classesbymodule の引数と同様ですが、2番目の引数で指定されたQMLモジュールに含まれるQML型（QMLの値型を除く）を一覧表示するために使用されます。

qmlvaluetypesbymodule

qmltypesbymodule 引数と同様ですが、代わりにQMLの値型を一覧表示します。

functionindex

functionindex 引数は、ドキュメント化されているすべてのメンバ関数をアルファベット順に網羅したリストを提供します。通常、次のようにしてQt の関数索引ページを生成するためにのみ使用されます。

/*!
    \page functions.html
    \title All Functions
    \ingroup funclists

    \brief All documented Qt functions listed alphabetically with a
    link to where each one is declared.

    This is the list of all documented member functions and global
    functions in the Qt API. Each function has a link to the
    class or header file where it is declared and documented.

    \generatelist functionindex
*/

legalese

legalese 引数は、QDocに対し、現在のドキュメントプロジェクト内のライセンス一覧を生成するよう指示します。各ライセンスは、 \legalese コマンドを使用して識別されます。

overviews

overviews 引数は、すべての \group ページの内容を連結して一覧を生成するよう指示するために使用されます。Qt では、この方法で概要ページを生成しています:

/*!
    \page overviews.html

    \title All Overviews and HOWTOs

    \generatelist overviews
*/

attributions

attributions 引数は、QDocに対して、ドキュメント内に帰属情報のリストを生成するよう指示するために使用されます。

related

related 引数は、 \group および \ingroup コマンドと組み合わせて使用し、指定されたグループに関連するすべての概要を一覧表示します。たとえば、「Qt を使ったプログラミング」のページは、次のように生成されます:

/*!
    \group qt-basic-concepts
    \title Programming with Qt

    \brief The basic architecture of the Qt cross-platform application and UI framework.

    Qt is a cross-platform application and UI framework for
    writing web-enabled applications for desktop, mobile, and
    embedded operating systems. This page contains links to
    articles and overviews explaining key components and
    techniuqes used in Qt development.

    \generatelist {related}
*/

このグループページにリストされている各ページには、次のコマンドが含まれています：

\ingroup qt-basic-concepts

関連項目 \annotatedlist。

\if

\if コマンドおよびそれに対応する\endif コマンドは、QDocコメントの一部を囲み、コマンドの引数で指定された条件が真の場合にのみ、その部分が組み込まれます。

このコマンドは、その行の残りの部分を読み取り、C++の#if文として解析します。

/*!
   \if defined(opensourceedition)

   \note This edition is for the development of
   \l{Qt Open Source Edition} {Free and Open Source}
   software only; see \l{Qt Commercial Editions}.

   \endif
*/

このQDocコメントは、opensourceedition というプリプロセッサシンボルが定義されており、かつ設定ファイル内の`defines`変数に指定されている場合にのみレンダリングされ、QDocが`#ifdef`と`#endif`で囲まれたコードを処理するようになります。

defines = opensourceedition

また、コマンドライン上でこのプリプロセッサシンボルを手動で定義することも可能です。詳細については、defines変数のドキュメントを参照してください。

関連項目 \endif、 \else、`defines` および誤った認識。

\endif

\endif コマンドおよび対応する\if コマンドは、QDocコメントの一部を囲み、 \if コマンドの引数で指定された条件が真の場合に、QDocコメントの一部を囲み込みます。

詳細については、 \if コマンドのドキュメントを参照してください。

関連項目 \if、 \else、定義、および虚偽。

\else

\else コマンドは、 \if コマンド内の条件が偽の場合の代替処理を指定します。

\else コマンドは、\if...\endifコマンド内でのみ使用できますが、選択肢が2つしかない場合に便利です。

\include

\include コマンドは、最初の引数で指定されたファイルの全部または一部をQDoc入力ストリームに送信し、QDocコメントスニペットとして処理させます。

このコマンドは、コマンドやテキストの断片をドキュメント内の複数の場所で使用する場合に便利です。ドキュメントにスニペットを挿入したい場所ならどこでも、\include コマンドを使用してください。含めるスニペットを含むファイルは、QDoc設定変数sourcedirsまたは exampledirsにリストされているパス下に配置されている必要があります。 そのファイルは、QDocによって解析される任意のソースファイル（あるいは\include コマンドが使用されているファイルそのものでも可）でも、その他のテキストファイルでも構いません。QDocによる解析対象ではない別のファイルにスニペットを保存するには、sources.fileextensionsにリストされていないファイル拡張子を使用してください。例えば、.qdocinc などです。

このコマンドには、1つ以上の引数を指定できます。最初の引数は常にファイル名です。ファイルの内容はQDocの入力形式、つまりQDocコマンドとテキストの連続である必要がありますが、QDocコメントの区切り文字（/ 、*!...、* 、/ ）は含めないでください。指定したファイル全体を含めたい場合は、2番目の引数を空にします。 ファイルの一部のみを含めたい場合は、以下の2引数形式を参照してください。以下に、1引数形式の例を示します。

/*!
    \page corefeatures.html
    \title Core Features

    \include examples/signalandslots.qdocinc
    \include examples/objectmodel.qdocinc
    \include examples/layoutmanagement.qdocinc
*/

\include filename snippet-identifier

ドキュメント内の複数の場所で使用したいQDocインクルードスニペットごとに、個別の.qdocinc ファイルを作成するのは時間の無駄です。特に、これらのファイルのすべてに著作権やライセンスの記載を記載しなければならないことを考えると、なおさらです。 インクルードするスニペットが複数ある場合は、それらをすべて1つのファイルにまとめ、それぞれを次のように囲むことができます：

//! [snippet-id1]

QDoc commands and text...

//! [snippet-id1]

//! [snippet-id2]

More QDoc commands and text...

//! [snippet-id2]

そうすれば、コマンドの2引数形式を使用できます：

\include examples/signalandslots.qdocinc snippet-id2
\include examples/objectmodel.qdocinc another-snippet-id

2番目の引数と同じ名前を持つ2つのタグの間に記述されたQDocコマンドとテキストのシーケンスが、QDocの入力ストリームに送信されます。スニペットをネストさせることも可能です。

追加の引数

QDoc 6.3 以降、\include コマンドに渡された追加の引数は、含まれるコンテンツへの文字列の挿入に使用されます。コンテンツ内の特定の位置に文字列を挿入するには、バックスラッシュの後に数字（1～9）を指定します。この数字は、引数リストの順序に対応しています。 QDocが空白文字を含め、引数を期待どおりに完全にレンダリングするようにするには、引数を中括弧で囲んでください。

たとえば、ファイルincludes.qdocinc に以下のスニペットがあるとします：

//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]

その場合、\include ファイル内の次の行：

\include includes.qdocinc {usage} {detailed output} {Verbose}

表示されるのは

詳細な出力を有効にするには、[Verbose ] > [Enable] を選択してください。

\meta

\meta コマンドは、ドキュメントにメタデータを追加するために使用されます。このコマンドには2つの引数があります。1つ目の引数はメタデータ属性の名前、2つ目の引数はその属性の値です。各引数は、次の例のように中括弧で囲む必要があります：

/*!
    \example demos/coffee
    \title Coffee Machine
    \brief A Qt Quick application with a state-based custom user interface.

    \meta {tags} {quick,embedded,states,touch}
    \meta {category} {Application Examples}
*/

多くのメタデータ属性には、それぞれ特定の目的があります：

メタデータの例

\meta コマンドのもう一つの用途は、メタデータ（タグ）を \example ドキュメントにメタデータ（タグ）を含めることです。デフォルトでは、QDocは例の \title およびモジュール名に基づいてサンプルタグを生成します。これらのタグはQt Creator の「ウェルカムモード」に表示され、ユーザーがサンプル一覧を閲覧する際の助けとなります。

\meta {tag} {tag1} または\meta {tags} {tag1,[tag2,...]} を使用して、追加のタグを作成できます。例えば：

/*!
    \example helloworld
    \title Hello World Example
    \meta {tags} {tutorial,basic}
*/

これにより、tutorial、basic、hello、world というタグが生成されます。「example」などの一般的な単語は無視されます。

例の除外

例を「動作しない」としてマークすると、生成されるマニフェストファイルからその例が除外され、事実上Qt Creator の「Welcome」モードから削除されます。

\meta {tag} {broken}

例のインストールパス

\meta コマンドに引数 `installpath ` を組み合わせることで、インストール済みの例の場所を指定できます。この値は、examplesinstallpath 設定変数で設定された値よりも優先されます。

/*!
    \example helloworld
    \title Hello World Example
    \meta {installpath} {tutorials}
*/

examplesinstallpath も参照してください。

ステータス

\meta コマンドのstatus 引数を使用すると、 \class または \qmltypeに対して、カスタムステータス説明を追加します。この説明は、その後、型リファレンスページの上部にある表に表示されます。

/*!
    \class QNativeInterface::QAndroidApplication
    \meta {status} {Android-specific}
*/

ステータス関連のコマンドも参照してください。

ドキュメントのメタデータ

\meta コマンドのkeywords 引数を使用すると、指定されたキーワードが生成されるドキュメントのメタデータとして追加されます：

\meta {keywords} {reference, internal}

HTML出力では、これらのキーワードは<meta name="keywords" content="..."> 要素として生成されます。

\noautolist

\noautolist コマンドは、C++ または QML モジュールページの下部に自動的に生成される、C++ クラスまたは QML 型の注釈付きリストを、それらのクラスや型が手動でリストアップされているため省略すべきであることを示します。このコマンドは、グループメンバーのリストを手動で記述する場合に、 \group コマンドと併用して、グループのメンバーが手動でリストされている場合に、そのリストを省略することもできます。

このコマンドは、必ず単独の行に記述する必要があります。例については Qt Quick Controls QML Types を参照してください。このページはqtquickcontrols2-qmlmodule.qdoc から生成されています。そこには、QtQuick.Controls モジュールに対する\qmlmodule コマンドを含む QDoc コメントがあります。同じコメントには、自動リスト生成を無効にする\noautolist コマンドや、 \generatelist ドキュメントの特定のセクションにQML型を一覧表示するための```コマンドも含まれています。

このコマンドは QDoc 5.6 で導入されました。

Qt 5.10 以降、このコマンドは \example ドキュメントにも適用できるようになり、これにより、サンプルプロジェクトに属するファイルや画像の自動生成リストが省略されるようになります。

\omit

\omit コマンドおよび対応する\endomit コマンドは、QDocにスキップさせたいドキュメントの範囲を指定します。例えば：

/*!
    \table
    \row
        \li Basic Widgets
        \li Basic GUI widgets such as buttons, comboboxes
           and scrollbars.

    \omit
    \row
        \li Component Model
        \li Interfaces and helper classes for the Qt
           Component Model.
    \endomit

    \row
        \li Database Classes
        \li Database related classes, e.g. for SQL databases.
    \endtable
*/

\raw (避けるべき！)

\raw コマンドおよびそれに対応する\endraw コマンドは、生のマークアップ言語コードのブロックを区切ります。

このコマンドは、コードのフォーマットを指定する引数を受け取ります。

QDocは、ユーザーが指定したフォーマットを生成する場合にのみ、指定されたコードを生成します。

たとえば、「\raw HTML」と指定した場合、QDocがHTMLドキュメントを生成するときにのみコードが生成されます。

\sincelist

\sincelist コマンドを実行すると、指定されたバージョンのドキュメント化された API に新たに追加された項目が詳細に一覧表示されます。使用例：

/*!
   \page newclasses612.html
   \title New Classes and Functions in 6.12
   \brief A comprehensive list of new classes and functions in 6.12.

   \sincelist 6.12
*/

\sincelistこのコマンドは、バージョン文字列という単一の引数を受け取ります。生成される出力には、バージョン文字列に一致する \since `since`句でマークされたすべての機能が含まれます。

\unicode

\unicode コマンドを使用すると、文書内に任意のUnicode文字を挿入することができます。

このコマンドは、文字を指定する整数の引数を受け取ります。デフォルトでは10進数が想定されますが、「0x」または「0」の接頭辞が指定された場合は、それぞれ16進数および8進数として扱われます。