トピックコマンド

トピックコマンドは、どのソースコード要素がドキュメント化されているかをQDocに指示します。一部のトピックコマンドでは、基盤となるソースコード要素に紐づかないドキュメントページを作成することができます。

QDocがQDocコメントを処理する際、まずそのソースコード要素の名前を指定するトピックコマンドを探し、コメントをソースコード内の要素に関連付けようとします。トピックコマンドが見つからない場合、QDocはそのコメントの直後に続くソースコード要素に関連付けようとします。 これらのいずれもうまくいかず、かつそのコメントに基となるソースコード要素がないことを示すトピックコマンド（例： \page）がない場合、そのコメントは破棄されます。

トピック・コマンドの引数は、通常、ドキュメント化対象のエンティティ名のみです。完全な名前を使用してください。場合によっては、引数に 2 番目のパラメータが含まれることもあります。例として、 \pageを参照してください。

\enum QComboBox::InsertPolicy

\fn コマンドは特殊なケースです。 \fn コマンドについては、クラス修飾子を含む関数のシグネチャを使用してください。

\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)

トピックコマンドはコメント内のどこにでも記述できますが、必ず単独の行に記述する必要があります。トピックコマンドをコメントの最初の行に記述するのが推奨されます。引数が複数行にまたがる場合は、各行（最後の行を除く）の末尾にバックスラッシュを付けるようにしてください。 さらに、QDocは括弧をカウントします。つまり、'(' に出会うと、それ以降のすべての内容を、閉じ括弧 ')' までをその引数として扱います。

トピックコマンドが異なる引数で繰り返された場合、両方のユニットに対して同じドキュメントが表示されます。

/*!
    \fn void PreviewWindow::setWindowFlags()
    \fn void ControllerWindow::setWindowFlags()

    Sets the widgets flags using the QWidget::setWindowFlags()
    function.

    Then runs through the available window flags, creating a text
    that contains the names of the flags that matches the flags
    parameter, displaying the text in the widgets text editor.
*/

PreviewWindow::setWindowFlags() とControllerWindow::setWindowFlags() の関数には、同じドキュメントが表示されます。

トピックコマンドによって生成されるファイルの命名規則

次のような多くのトピックコマンドでは、 \page、QDoc はドキュメントの処理時にファイルを生成します。

QDocは、各ファイルの名前を正規化してからディスクに書き込みます。その際、以下の処理が行われます：

• 英数字以外の文字の連続はすべて、ハイフン「-」に置き換えられます。
• すべての大文字は、対応する小文字に置き換えられます。
• 末尾のハイフンはすべて削除されます。

たとえば、次のコマンドを実行すると、this-generates-a-file-and-writes-it-to-disk.html という名前のファイルが生成されます：

\page this_generates_a_file_(and_writes_it_to_DISK)-.html

この例が示すように、コマンドで指定されたファイル名は、実際にディスクに書き込まれるファイル名とは異なる場合があります。

生成されるファイルの接頭辞と接尾辞

QDocがファイルを生成する際、そのファイルがどの要素を文書化するかに応じて、プレフィックス、サフィックス、あるいはその両方が追加される場合があります。

以下の表は、さまざまな要素に対するこれらの接頭辞および接尾辞を示しています。

\class

\class コマンドは、C++クラス、C/C++構造体、またはユニオンをドキュメント化するためのものです。引数には、クラスの完全修飾名指定します。このコマンドにより、そのクラスがパブリックAPIの一部であることをQDocに通知し、詳細な説明を入力できるようになります。

/*!
    \class QMap::iterator
    \inmodule QtCore

    \brief The QMap::iterator class provides an STL-style
    non-const iterator for QMap and QMultiMap.

    QMap features both \l{STL-style iterators} and
    \l{Java-style iterators}. The STL-style iterators ...
*/

指定されたクラスの HTML ドキュメントは、クラス名を小文字に変換し、二重コロン（::）を「-」に置き換えた名前の.html ファイルに書き込まれます。たとえば、QMap::iterator クラスのドキュメントはqmap-iterator.html に書き込まれます。

このファイルには、\class コメントからのクラス説明に加え、すべてのクラスメメンバーに関する QDoc コメントから生成されたドキュメント（クラスの型、プロパティ、関数、シグナル、スロットのリスト）が含まれます。

クラスの詳細な説明に加え、\class コメントには通常、 \inmodule コマンドと \brief descriptionも含まれています。以下に非常に簡単な例を示します：

/*!
    \class PreviewWindow
    \inmodule CustomWidgets
    \brief The PreviewWindow class is a custom widget.
           displaying the names of its currently set
           window flags in a read-only text editor.

    \ingroup miscellaneous

    The PreviewWindow class inherits QWidget. The widget
    displays the names of its window flags set with the \l
    {function} {setWindowFlags()} function. It is also
    provided with a QPushButton that closes the window.

    ...

    \sa QWidget
*/

QDocがこの\class をどのように表示するかは、style.css ファイルの設定によって異なります。

\concept

\concept コマンドは、C++20 のコンセプトごとに個別のページを作成し、そのコンセプトを参照するテンプレート制約を持つ、ドキュメント化された型や関数をまとめて表示します。引数には、Clang が宣言に対して報告する名前と一致する、コンセプトの完全修飾名を使用します。ファイルスコープ内のコンセプトは名前のみを使用しますが、名前空間内のコンセプトには、algorithms::Ordered のような完全修飾名が必要です。

型や関数は、自動的にそのコンセプトのページに追加されます。QDocがドキュメント化された宣言を解析する際、その宣言の制約を検査し、参照されているコンセプトに対してその宣言を登録します。制約の対象となる項目自体に対して、\ingroup や\inmodule のような形式のコマンドを実行する必要はありません。

QDoc は、C++20 の制約の 3 つの構文形式を認識します:

• 明示的なrequires 節。これは、テンプレートヘッダー（template <typename T> requires Ordered<T> ）に記述されている場合でも、関数シグネチャの末尾に記述されている場合でも認識されます。
• 制約付きのauto パラメータ（void sort(Ordered auto& range) ）。
• テンプレートパラメータに直接記述されたコンセプト（template <Ordered T> class SortedSet ）。

\concept コマンドの後に、通常は \inmodule コマンドと \brief 説明が続きます。コメント本文は詳細な説明として表示され、 \section1 見出しは、他のドキュメントページと同様に機能します。

/*!
    \concept Ordered
    \inmodule Algorithms

    \brief A type that admits a total order.

    The Ordered concept is satisfied by any type that supplies the
    relational operators \c {<}, \c {<=}, \c {>}, and \c {>=}, and for
    which those operators induce a strict total order.

    \section1 Definition

    Ordered evaluates to \c true when \c {T} is totally ordered
    and to \c false otherwise.
*/

QDocは、その概念のリファレンスページを生成します。 上記の例の場合、そのページはordered.html となり、概要、詳細な説明、および「使用箇所」セクションが含まれます。「使用箇所」セクションには、生成されたドキュメントに含まれ、その制約がOrdered を参照している、ドキュメント化された型や関数がリストアップされています。各エントリはリンクとして表示され、その後に、そのエントリ自身のドキュメントからの\brief による説明が続きます。これは、\group や\module ページ上のリストと同じ形式です。

標準ライブラリに含まれる概念など、ドキュメント化されていない概念への参照は、何も表示されずに無視されます。そのような参照はページを生成せず、警告も出力されません。

関連項目 \group, \module、および \inmodule。

\enum

\enum コマンドは、C++のenum型をドキュメント化するためのものです。引数には、enum型の完全な名前を指定します。

列挙型の値は、\enum コメント内で \value コマンドを使用して記述されます。列挙型の値が\value でドキュメント化されていない場合、QDocは警告を出力します。これらの警告は、 \omitvalue コマンドを使用して、その列挙型の値をドキュメント化しないよう QDoc に指示することで回避できます。列挙型のドキュメントは、その列挙型が定義されているクラスのリファレンスページ、ヘッダーファイルページ、または名前空間ページに表示されます。例として、Qt 名前空間内の列挙型Corner を考えてみましょう：

enum Corner {
    TopLeftCorner = 0x00000,
    TopRightCorner = 0x00001,
    BottomLeftCorner = 0x00002,
    BottomRightCorner = 0x00003
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
    ,TopLeft = TopLeftCorner,
    TopRight = TopRightCorner,
    BottomLeft = BottomLeftCorner,
    BottomRight = BottomRightCorner
#endif
};

この列挙型は、次のようにドキュメント化できます:

/*!
    \enum Qt::Corner

    This enum type specifies a corner in a rectangle:

    \value TopLeftCorner
           The top-left corner of the rectangle.
    \value TopRightCorner
           The top-right corner of the rectangle.
    \value BottomLeftCorner
           The bottom-left corner of the rectangle.
    \value BottomRightCorner
           The bottom-right corner of the rectangle.

    \omitvalue TopLeft
    \omitvalue TopRight
    \omitvalue BottomLeft
    \omitvalue BottomRight
               Bottom-right (omitted; not documented).
*/

名前空間修飾子が含まれている点に注意してください。

関連項目 \value および \omitvalueを参照してください。

\example

\example コマンドは、例をドキュメント化するためのものです。引数には、QDoc設定ファイルのexampledirs変数にリストされているパスのいずれかを基準とした、その例の相対パスを指定します。

ドキュメントページは `modulename-path-to-example.html` に出力されます。QDoc は、 \noautolist command が使用された場合、またはプロジェクトに対して設定変数url.examples が定義されている場合は除きます。

たとえば、exampledirsに$QTDIR/examples/widgets/imageviewer が含まれている場合、

/*!
    \example widgets/imageviewer
    \title ImageViewer Example
    \subtitle

    The example shows how to combine QLabel and QScrollArea
    to display an image.

    ...
*/

関連項目：\noautolist,url.examples, \meta

\externalpage

\externalpage コマンドは、外部URLにタイトルを割り当てます。

/*!
    \externalpage https://doc.qt.io/
    \title Qt Documentation Site
*/

これにより、ドキュメント内に次のような形で外部ページへのリンクを挿入することができます:

/*!
    At the \l {Qt Documentation Site} you can find the latest
    documentation for Qt, Qt Creator, the Qt SDK and much more.
*/

\externalpage コマンドを使用せずに同じ結果を得るには、ドキュメント内にアドレスを直接記述する必要があります：

/*!
    At the \l {http://doc.qt.io/}{Qt Documentation Site}
    you can find the latest documentation for Qt, Qt Creator, the Qt SDK
    and much more.
*/

\externalpage コマンドを使用すれば、ドキュメントのメンテナンスが容易になります。アドレスが変更された場合でも、\externalpage コマンドの引数を変更するだけで済みます。

\fn (関数)

\fn コマンドは、関数のドキュメントを作成するためのものです。引数には、テンプレートパラメータ（ある場合）、戻り値の型、constの有無、および型付きの形式引数のリストを含む、関数のシグネチャを指定します。指定された関数が存在しない場合、QDocは警告を出力します。

このコマンドは、QDoc によって完全な型が推論できる場合でも、関数の型として `auto ` を受け入れます。状況によっては、関数の実際の型ではなく`auto`を使用する方が望ましい場合があります。\fn` コマンドで戻り値の型として `auto ` を使用することで、`auto`キーワードなしで定義された型に対しても、著者がこれを明示的に指定できるようになります。

QDoc バージョン 6.0 以降、\fn コマンドは、ヘッダーで明示的に宣言されていないが、コンパイラによって暗黙的に生成されるクラスメメンバー（デフォルトコンストラクタとデストラクタ、コピーコンストラクタと移動コピーコンストラクタ、代入演算子、および移動代入演算子）のドキュメント作成に使用できます。

隠しフレンドをドキュメント化する際は、クラス修飾構文または修飾なしのフリー関数構文のいずれかを使用できます。例えば、次のような場合です：

class Foo {
   ...
   friend bool operator==(const Foo&, const Foo&) { ... }
   ...
}

このコマンドは、"\fn Foo::operator==(const Foo&, const Foo&)" と記述することも、フリー関数形式の"\fn bool operator==(const Foo&, const Foo&)" と記述することもできます。QDoc は、関数のパラメータ型で参照されているクラスを検索することで、隠しフレンドを解決します。

/*!
    \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const

    Returns \c true if this toolbar is dockable in the given
    \a area; otherwise returns \c false.
*/

関連項目 \overload.

\group

\group コマンドは、指定されたグループに属するクラス、ページ、またはその他のエンティティを一覧表示する独立したページを作成します。引数にはグループ名を指定します。

クラスをグループに含めるには、 \ingroup コマンドを使用して行います。概要ページも同様のコマンドでグループに関連付けることができますが、概要ページのリストを取得するには、 \generatelist コマンドを使用して明示的に要求する必要があります（以下の例を参照）。

\group コマンドの後に、通常は \title コマンドと、グループの簡単な紹介文が続きます。グループの HTML ページは、<グループ名（小文字）>.html という名前の.html ファイルに書き込まれます。

グループ内の各エンティティは、（ページタイトルまたはクラス名を使用した）リンクとして一覧表示され、その後に \brief そのエンティティのドキュメント内の`xml-ph-0000@deepl.internal`コマンドによる説明が続きます。

/*!
    \group io
    \title Input/Output and Networking
*/

QDocは、グループページio.html を生成します。

なお、そのグループに関連する概要ページは、 \generatelist コマンドにrelated 引数を指定して、明示的にリストアップする必要があることに注意してください。

/*!
    \group architecture

    \title Architecture

    These documents describe aspects of Qt's architecture
    and design, including overviews of core Qt features and
    technologies.

    \generatelist{related}
*/

関連項目 \ingroup、 \annotatedlist、 \generatelist、および \noautolist。

\headerfile

\headerfile コマンドは、ヘッダーファイル内で宣言されているが、名前空間には属していないグローバル関数、型、およびマクロをドキュメント化するためのものです。引数にはヘッダーファイルの名前を指定します。HTMLページは、ヘッダーファイルの引数から生成された.html ファイルに書き込まれます。

ドキュメント化対象のヘッダーファイル内で宣言されている関数、型、またはマクロに関するドキュメントは、 \relates コマンドを使用して、そのヘッダーファイルに宣言されている関数、型、またはマクロのドキュメントがヘッダーファイルのページに組み込まれます。

引数がヘッダーファイルとして存在しない場合でも、\headerfile コマンドは、そのヘッダーファイルのドキュメントページを作成します。

/*!
   \headerfile <QtAlgorithms>

   \title Generic Algorithms

   \brief The <QtAlgorithms> header file provides
    generic template-based algorithms.

   Qt provides a number of global template functions in \c
   <QtAlgorithms> that work on containers and perform
   well-know algorithms.
*/

QDocは、ヘッダーファイルのページを生成します。qtalgorithms.html 。

関連項目 \inheaderfile。

\macro

\macro コマンドは、C++マクロのドキュメントを作成するためのものです。引数には、Q_ASSERT()のような関数風のマクロ、Q_PROPERTY()のような宣言形式のマクロ、およびQ_OBJECT のような括弧のないマクロの、3つの形式のいずれかでマクロを指定します。

\macro コメントには、 \relates コマンドを含んでいる必要があります。そうしないと、ドキュメントが失われてしまいます。

\module

\module は、コマンドの引数で指定されたモジュールに属するクラスを一覧表示するページを作成します。 \inmodule\class コメント内に含まれることで、そのモジュールに属することになります。

\module コマンドの後には、通常、 \title および \brief コマンドが続きます。各クラスは、クラスリファレンスページへのリンクとして一覧表示され、その後にそのクラスの \brief コマンドからのテキストが続きます。例えば：

/*!
    \module QtNetwork

    \title Qt Network Module

    \brief Contains classes for writing TCP/IP clients and servers.

    The network module provides classes to make network
    programming easier and portable. It offers both
    high-level classes such as QNetworkAccessManager that
    implements application-level protocols, and
    lower-level classes such as QTcpSocket, QTcpServer, and
    QUdpSocket.
*/

ここで \noautolist コマンドを使用すると、末尾に自動的に生成されるクラス一覧を省略することができます。

関連項目 \inmodule

\namespace

\namespace コマンドは、引数として指定された名前のC++名前空間の内容をドキュメント化するためのものです。QDocが名前空間に対して生成するリファレンスページは、C++クラスに対して生成されるリファレンスページと同様です。

/*!
    \namespace Qt

    \brief Contains miscellaneous identifiers used throughout the Qt library.
*/

なお、C++ では、特定の名前空間を複数のモジュールで使用できますが、異なるモジュールに属する C++ 要素が同じ名前空間内で宣言される場合、その名前空間自体のドキュメントは 1 つのモジュール内でのみ記述する必要があります。 たとえば、上記の例にある namespace Qt には、QtCore とQtGui の両方の型や関数が含まれていますが、\namespace コマンドによるドキュメント化はQtCore でのみ行われています。

\page

\page コマンドは、独立したドキュメントページを作成するためのものです。

\page コマンドは、QDoc がページを保存するファイル名を表す単一の引数を受け取ります。

ページのタイトルは、 \title コマンドを使用して設定します。

/*!
   \page aboutqt.html

   \title About Qt

   Qt is a C++ toolkit for cross-platform GUI
   application development. Qt provides single-source
   portability across Microsoft Windows, macOS, Linux,
   and all major commercial Unix variants.

   Qt provides application developers with all the
   functionality needed to build applications with
   state-of-the-art graphical user interfaces. Qt is fully
   object-oriented, easily extensible, and allows true
   component programming.

   ...
*/

QDocはこのページをaboutqt.html でレンダリングします。

\property

\property コマンドは、Qt プロパティをドキュメント化するためのものです。引数には、プロパティの完全な名前を指定します。

プロパティは、Q_PROPERTY() マクロを使用して定義されます。このマクロは、プロパティ名と、その set、reset、get 関数を引数として受け取ります。

Q_PROPERTY(QString state READ state WRITE setState)

set、reset、get 関数については、個別にドキュメントを作成する必要はなく、プロパティのドキュメントを作成すれば十分です。QDoc は、プロパティのドキュメントに表示されるアクセス関数のリストを生成します。このドキュメントは、そのプロパティを定義するクラスのドキュメント内に配置されます。

\property コマンドのコメントには、通常、 \brief コマンドで構成されます。プロパティの場合、 \brief コマンドの引数は、プロパティの1行の説明に含まれる文の断片です。このコマンドは、説明に関して \variable コマンドと同様の記述規則に従います。

/*!
    \property QPushButton::flat
    \brief Whether the border is disabled.

    This property's default is false.
*/

\qmlattachedmethod

\qmlattachedmethod コマンドは、あるQML型にアタッチされたメソッド（アタッチされたプロパティ）をドキュメント化するために使用します。\qmlattachedmethod コマンドは、 \qmlmethod コマンドと同様に使用されます。

引数はその行の残りの部分であり、戻り値の型から始まり、その後にメソッドが宣言されている QML 型名、:: 修飾子、そして最後にパラメータの型と名前を括弧で囲んだメソッド名が続く、完全なメソッドシグネチャでなければなりません。メソッドが引数を取らない場合は、() を使用してください。

たとえば、ToolTip 型に定義されたshow() という名前のアタッチドメソッドをドキュメント化するには、次のようにします。

/*!
    \qmlattachedmethod void QtQuick.Controls::ToolTip::show(string text, int timeout = -1)

    This attached method shows the shared tool tip with \a text for
    \a timeout milliseconds. You can attach the method to any item.
*/

QDoc は、このドキュメントをToolTip 型の QML リファレンスページに掲載します。

\qmlattachedproperty

\qmlattachedproperty コマンドは、ある QML 型にアタッチされる QML プロパティをドキュメント化するためのものです。「アタッチされたプロパティ」を参照してください。引数はその行の残りの部分です。引数はプロパティ型で始まり、その後にプロパティが宣言されている QML 型名、:: 修飾子、そして最後にプロパティ名が続く必要があります。

たとえば、ListView 型に対して、isCurrentItem という名前のブール型のQMLアタッチドプロパティをドキュメント化するには、次のように記述します。

/*!
    \qmlattachedproperty bool ListView::isCurrentItem

    This attached property is \c true if this delegate is the current
    item; otherwise false.

    It is attached to each instance of the delegate.

    This property may be used to adjust the appearance of the current
    item, for example:

    \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
*/

QDocは、このアタッチドプロパティをListView タイプのQMLリファレンスページに掲載します。

\qmlattachedsignal

\qmlattachedsignal コマンドは、アタッチ可能なシグナルをドキュメント化するためのものです。\qmlattachedsignal コマンドは、 \qmlsignal コマンドと同様に使用されます。

引数には、その行の残りの部分を使用します。これには、シグナルが宣言されている QML 型の名前、:: 修飾子、そして最後にシグナル名を指定する必要があります。たとえば、GridView 要素内でadd() という名前の QML アタッチメントシグナルは、次のようにドキュメント化されます:

/*!
    \qmlattachedsignal GridView::add()
    This attached signal is emitted immediately after an item is added to the view.
*/

QDocは、このドキュメントをGridView 要素のQMLリファレンスページに含めています。

\qmlvaluetype

\qmlvaluetype コマンドは、QML 用の値型をドキュメント化するためのものです。このコマンドは、唯一の引数として型名を受け取ります。

\qmlvaluetypeは、機能的には \qmltype コマンドと機能的に同一です。唯一の違いは、その型がQML 値型としてタイトル付けされ（グループ化される）点です。

\qmlclass

このコマンドは非推奨です。代わりに \qmltype を使用してください。

\qmlenum

\qmlenum コマンドは、QMLの列挙型をドキュメント化するためのものです。このコマンドは、親となるQML型を含み、必要に応じてQMLモジュールも指定した列挙型の完全な名前を、単一の引数として受け取ります。

列挙子とその説明は、 \value コマンドを使用して記述されます。

たとえば、

/*!
    \qmlenum My.Module::Color::Channel
    \brief Specifies a color channel in the RGB colorspace.

    \value R
           Red color channel

    \value G
           Green color channel

    \value B
           Blue color channel
*/

これにより、Color.R、Color.G、Color.B の 3 つの列挙子を持つ列挙型Channel のドキュメントが生成されます。デフォルトでは、親の QML 型名が列挙子の接頭辞として使用されます。

qdoccmd{value} コマンドの最初の引数にすでに接頭辞が含まれている場合は、その接頭辞がそのまま使用されます：

\value Channel.R
       Red color channel
\value Channel.G
       Green color channel
\value Channel.B
       Blue color channel

ここでは、列挙子がChannel.R、Channel.G、Channel.B として一覧表示されます。

あるいは、既存の C++ \enum トピックから、 \qmlenumeratorsfrom コマンドを使用することで、既存のC++トピックから列挙型のドキュメントを複製することも可能です。

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

関連項目 \qmlenumeratorsfrom。

\qmlmethod

\qmlmethod コマンドは、QMLメソッドのドキュメントを作成するためのものです。引数には完全なメソッドのシグネチャを指定し、戻り値の型、および括弧で囲まれたパラメータ名と型を含める必要があります。メソッドが引数を受け取らない場合は、() を使用してください。

/*!
    \qmlmethod void TextInput::select(int start, int end)

    Causes the text from \a start to \a end to be selected.

    If either start or end is out of range, the selection is not changed.

    After having called this, selectionStart will become the lesser, and
    selectionEnd the greater (regardless of the order passed to this method).

   \sa selectionStart, selectionEnd
*/

QDoc は、このドキュメントを `TextInput ` 型の型リファレンスページに掲載します。

\qmltype

\qmltype コマンドは、QML 型のドキュメントを作成するためのものです。このコマンドには引数が 1 つあり、それは QML 型の名前です。

そのQML型に対応するC++クラスがある場合は、 \nativetype context コマンドを使用してそのクラスを指定できます。

`xml-ph-0000@deepl.internal` \inqmlmodule コマンドは、その型が属するQMLモジュールを文書化します。このコマンドに渡される引数は、文書化された \qmlmodule ページと一致している必要があります。

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

ここで、 \qmltype コメントには \nativetype が含まれており、TransformがC++クラスQGraphicsTransform のQML版であることを指定しています。\qmltype コメントには、すべてのQML型がnewであるため、常に \since コマンドを含める必要があります。また、 \brief descriptionを含める必要があります。QML型がQML型グループのメンバーである場合、\qmltype コメントには1つ以上の \ingroup commandを含める必要があります。

\qmlsingletontype

\qmlsingletontype コマンドは、QML シングルトン型を明示的にドキュメント化するためのものです。このコマンドは機能的には \qmltypeと機能的には同一ですが、C++の実装に関係なく、その型を明示的にシングルトンとしてマークします。

QMLのシングルトン型は、QMLエンジン内にインスタンスが1つだけ存在することを保証します。シングルトンとしての指定は、生成されたドキュメントのタイトルに「(Singleton)」という表記と説明文として表示されます。

/*!
    \qmlsingletontype Settings
    \inqmlmodule MyApp

    \brief Provides application-wide settings as a singleton.

    The Settings type is a singleton that maintains application
    configuration. Access it directly without instantiation.
*/

QML_SINGLETON マクロを使用するC++クラスについては、 \qmltype を使用することを推奨します。QDocはC++コードからシングルトンの性質を自動的に検出するためです。

関連項目 \qmluncreatabletypeを参照してください。

\qmluncreatabletype

\qmluncreatabletype コマンドは、QMLの型システムに登録されているものの、QML内で直接インスタンス化できない型を明示的に文書化するためのものです。

このコマンドは機能的には \qmltypeと機能的には同一ですが、C++ での実装にかかわらず、その型を明示的に「生成不可」としてマークします。

この「作成不可」の指定は、生成されたドキュメントのタイトルに「(作成不可)」という表示と、説明文として記載されます。

/*!
    \qmluncreatabletype Dialog
    \inqmlmodule QtQuick.Dialogs

    \brief The base type of native dialogs.
*/

QML_UNCREATABLE マクロを使用するC++クラスについては、 \qmltype を使用することをお勧めします。QDoc は C++ コードから作成不可能な性質を自動的に検出するためです。

\qmluncreatabletype コマンドは、Qt 6.12 で QDoc に導入されました。

関連項目 \qmlsingletontype。

\qmlproperty

\qmlproperty コマンドは、QMLプロパティのドキュメントを作成するためのものです。引数は、その行の残りの部分です。引数のテキストには、プロパティの型、その後にQMLの型名、:: 修飾子、そして最後にプロパティ名を記述する必要があります。QML型Translate にx という名前のQMLプロパティがあり、そのプロパティの型がreal である場合、その\qmlproperty は次のようになります:

/*!
    \qmlproperty real Translate::x

    The translation along the X axis.
*/

QDocは、このQMLプロパティをTranslate 型のQMLリファレンスページに掲載します。

\default コマンドは、プロパティのデフォルト値を記述するために使用されます：

\qmlproperty real AxisHelper::gridOpacity
\default 0.5

QMLプロパティがC++の列挙型を公開している場合、そのQMLプロパティはenumeration 型で定義されます：

\qmlproperty enumeration ParticleShape3D::ShapeType

列挙型のプロパティや、フラグのビット単位の組み合わせを保持するプロパティでは、 \value コマンドを使用して、許容される値をドキュメント化できます。

\qmlproperty enumeration Buffer::textureFilterOperation
Specifies the texture filtering mode...
\value Buffer.Nearest Use nearest-neighbor filtering.

QDoc では、QML モジュール識別子を含む完全修飾プロパティ名も指定可能です：

\qmlproperty bool QtQuick.Controls::Button::highlighted

指定する場合、モジュール識別子（上記のQtQuick.Controls ）は、関連する ドキュメント内の \inqmlmodule\qmltype コマンドに渡される値と一致している必要があります。プロパティが属する QML 型の名前が、ドキュメントプロジェクト内のすべての型の中で一意である場合は、モジュール識別子を省略できます。

\qmlsignal

\qmlsignal コマンドは、QML シグナルをドキュメント化するためのものです。引数は、その行の残りの部分です。引数には、シグナルが宣言されている QML タイプ、:: 修飾子、そして最後にシグナル名を指定する必要があります。clicked() という名前の QML シグナルがある場合、そのドキュメントは次のようになります:

/*!
    \qmlsignal MouseArea::clicked(MouseEvent mouse)

    This signal is emitted when there is a click. A click is defined as a
    press followed by a release, both inside the MouseArea.
*/

QDocは、このドキュメントをMouseArea 型のQMLリファレンスページに掲載します。

\qmlmodule

\qmlmodule コマンドを使用して、QML のモジュールページを作成します。QMLモジュールページとは、QMLタイプや関連資料の集合体です。このコマンドは、オプションで<VERSION> 番号を引数として受け取り、groupコマンドと類似しています。

QML タイプをモジュールに関連付けるには、そのタイプを記述するコメントブロックに \inqmlmodule コマンドを追加することで、QML型はモジュールに関連付けられます。モジュール名と2つのコロン（:: ）を接頭辞として使用することで、QMLモジュールの任意のメンバにリンクすることができます。

/*!
    A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
*/

QDocは、そのモジュールのすべてのメンバを一覧表示するページを生成します。

/*!
    \qmlmodule ClickableComponents

    This is a list of the Clickable Components set. A Clickable component
    responds to a \c clicked() event.
*/

\inqmlmodule

\inqmlmodule QML タイプを特定の QML モジュールインポートの下で利用可能としてマークするには、 \qmltype トピック内にxml-ph-0000@deepl.internalコマンドを挿入することで、そのQML型を特定のQMLモジュールインポートの下で利用可能としてマークします。このコマンドは、バージョン番号を含まないモジュール（インポート）名を唯一の引数として受け取ります。

QML モジュール名は、(\qmlmodule コマンド）で文書化されているQMLモジュールと一致している必要があります。

/*!
    \qmltype ClickableButton
    \inqmlmodule ClickableComponents

    A clickable button that responds to the \c click() event.
*/

QDocは、QML型リファレンスページの上部にある表に、1行のimport文（import <qmlmodule>）を出力します。

QML タイプへのリンクを行う際、リンク先には QML モジュール識別子が含まれる場合があります。例：

\l {ClickableComponents::}{ClickableButton}

ClickableButton をリンクテキストとする、型リファレンスページへのリンク。

\instantiates

\instantiates コマンドは、Qt 6.8以降で非推奨となっています。代わりに \nativetype を使用してください。

\nativetype

\nativetype コマンドは、 \qmltype topic コマンドと組み合わせて使用する必要があります。このコマンドは、引数として C++ クラスを受け取ります。QDoc がその C++ クラスを見つけられない場合、警告が表示されます。このコマンドは Qt 6.8 で導入されました。

\nativetype コマンドを使用して、C++ での型名を指定します。これにより、QML 型のドキュメントに生成される要件ブロックに「In C++」エントリが確実に含まれるようになります。また、その C++ クラスには、対応する「In QML」エントリが作成されます。

1つのQML型につき、ネイティブ型は1つしか持つことができません。再定義が行われた場合、QDocは警告を出力します。ただし、複数のQML型が同じC++クラスをネイティブ型として持つことは可能です。C++クラスのドキュメントには、QML内の対応するすべての型のリストが含まれます。

/*!
    \qmltype Transform
    \nativetype QGraphicsTransform
    \inqmlmodule QtQuick

    \brief Provides a way to build advanced transformations on Items.

    The Transform element is a base type which cannot be
    instantiated directly.
*/

ここで、 \qmltype トピックには \nativetype を含み、TransformがC++ではQGraphicsTransform と呼ばれることを指定しています。

\typealias

\typealias コマンドは \typedefと似ていますが、C++の型エイリアスを記述する場合に限定されます：

class Foo
{
public:
    using ptr = void*;
// ...
}

これは次のようにドキュメント化できます。

/*!
    \typealias Foo::ptr
*/

\typealias コマンドは、QDoc 5.15で導入されました。

関連項目 \typedef.

\typedef

\typedef コマンドは、C++のtypedefのドキュメントを作成するためのものです。引数にはtypedefの名前を指定します。このtypedefに関するドキュメントは、そのtypedefが宣言されているクラス、名前空間、またはヘッダーファイルのリファレンスドキュメントに組み込まれます。\typedef をクラス、名前空間、またはヘッダーファイルに関連付けるには、\typedef コメント内に \relates コマンドを含める必要があります。

/*!
    \typedef QObjectList
    \relates QObject

    Synonym for QList<QObject>.
*/

その他のtypedefは、それらを定義するクラスのリファレンスページに記載されています。

/*!
    \typedef QList::Iterator

    Qt-style synonym for QList::iterator.
*/

関連項目 \typealias。

\variable

\variable コマンドは、クラスのメンバ変数や定数をドキュメント化するためのものです。引数には、変数名または定数名を指定します。\variable コマンドによるコメントには、 \brief コマンドを含みます。QDocは、\brief コマンドのテキストに基づいてドキュメントを生成します。

ドキュメントは、関連するクラス、ヘッダーファイル、または名前空間のドキュメント内に配置されます。

メンバ変数の場合：

/*!
    \variable QStyleOption::palette
    \brief The palette that should be used when painting
           the control
*/

\variable コマンドを使用して、定数をドキュメント化することもできます。たとえば、QTreeWidgetItem クラスにType およびUserType という定数があるとします:

enum { Type = 0, UserType = 1000 };

これらに対しては、\variable コマンドを次のように使用できます:

/*!
    \variable QTreeWidgetItem::Type

    The default type for tree widget items.

    \sa UserType, type()
*/

/*!
    \variable QTreeWidgetItem::UserType

    The minimum value for custom types. Values below
    UserType are reserved by Qt.

    \sa Type, type()
*/