主题命令
主题命令告诉 QDoc 哪个源码元素正在被记录。一些主题命令允许你创建不与任何底层源码元素相联系的文档页面。
当 QDoc 处理 QDoc 注释时，它首先会尝试通过查找命名源码元素的主题命令来将注释与源码中的一个元素关联。如果没有主题命令，QDoc 会尝试将注释连接到紧跟注释的源代元素。如果它不能执行这些操作，并且没有主题命令表明该注释没有底层源码元素（例如 \page）的话，那么该注释将被丢弃。
被记录的实体的名称通常是主题命令的唯一参数。使用完整的名称。有时参数中有两个参数。参考 \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 生成文件时，它可能会添加前缀、后缀或两者，这取决于该文件要记录的元素。
下表显示了各种元素的前缀和后缀。
| 元素 | 前缀 | 后缀 | 命令 |
|---|---|---|---|
| QML Modules | 无 | "-qmlmodule" | \qmlmodule |
| Modules | 无 | "-module" | \module |
| Examples | 项目名称，来自 project 配置变量，后跟连字符。 | "-example" | \example |
| QML Types | QML 的输出前缀，来自 outputprefixes 配置变量。 如果 QDoc 知道包含此类型的模块，那么模块的名字就会作为前缀加入，后面是由 outputsuffixes 配置变量 定义的 QML 输出后缀和一个连字符。 | None | \qmltype |
\class
\class 命令用于记录 C++ 类。参数是类的完整名称。该命令告诉 QDoc 一个类是公共 API 的一部分，并让你输入详细描述。
/ *! \class QMap::iterator \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 注释通常包含一个 \brief 命令和一个或多个 标记命令。有关示例，请参见任何 Qt 类的 \class 命令。下面是一个非常简单的例子。
/ *! \class PreviewWindow \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 文件，但 class 参考页面的大致轮廓如下所示：
PreviewWindow Class Reference
The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a read-only text editor. More...
Properties
Public Functions
- PreviewWindow(QWidget *parent = 0)
- void setWindowFlags(Qt::WindowFlags flags)
Public Slots
Additional Inherited Members
- 1 signal inherited from QWidget
- 1 signal inherited from QObject
- 4 static public members inherited from QWidget
- 4 static public members inherited from QObject
- 39 protected functions inherited from QWidget
- 7 protected functions inherited from QObject
Detailed Description
The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a read-only text editor.
The PreviewWindow class inherits QWidget. The widget displays the names of its window flags set with the setWindowFlags() function. It is also provided with a QPushButton that closes the window.
...
See also QWidget.
Member Function Documentation
PreviewWindow(QWidget *parent = 0)
Constructs a preview window widget with parent.
setWindowFlags(Qt::WindowFlags flags)
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.
\enum
\enum 命令用于记录 C++ 枚举类型。参数是枚举类型的全名。
枚举值使用 \value 命令记录在 \enum 注释中。如果枚举值没有用 \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). * /
请注意包含命名空间限定符。QDoc 将在 qt.html 中呈现这个枚举类型，如下所示：
enum Qt::Corner
This enum type specifies a corner in a rectangle:
Constant Value Description Qt::TopLeftCorner 0x00000 The top-left corner of the rectangle. Qt::TopRightCorner 0x00001 The top-right corner of the rectangle. Qt::BottomLeftCorner 0x00002 The bottom-left corner of the rectangle. Qt::BottomRightCorner 0x00003 The bottom-right corner of the rectangle.
参见 \value 和 \omitvalue。
\example
\example 命令用于记录示例。参数是 QDoc 配置文件中 exampledirs 变量中列出的路径之一。
文档页面将输出到 modulename-path-to-example.html。 QDoc 将在页面末尾添加所有示例的源文件和图像文件的列表，除非使用了 \noautolist 命令或为项目定义了配置变量 url.examples。
例如，如果 exampledirs 包含 contains $QTDIR/examples/widgets/imageviewer，那么
/ *! \example widgets/imageviewer \title ImageViewer Example \subtitle The example shows how to combine QLabel and QScrollArea to display an image. ... * /
QDoc 在 widgets-imageviewer.html 渲染该示例：
Image Viewer Example
The example shows how to combine QLabel and QScrollArea to display an image.
Files:
...
参见： \generatelist examplefiles，\noautolist，url.examples，\meta
\externalpage
The \externalpage 命令将标题分配给外部 URL。
/ *! \externalpage http://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. * /
QDoc 渲染后：
At the 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 (function)
\fn 命令用于记录函数。参数是函数的签名，包括它的模板参数（如果有的话）、返回类型、常量和具有类型的形式参数列表。如果命名的函数不存在，QDoc 会发出警告。
从 QDoc 6.0 版开始，\fn 命令可用于记录未在头文件中显式声明，但由编译器隐式生成的类成员； 默认构造函数和析构函数、复制构造函数和移动复制构造函数、赋值运算符和移动赋值运算符。
当记录一个隐藏的友元时，需要在函数名前面加上类的类名。例如，对于：
class Foo { ... friend bool operator==(const Foo&, const Foo&) { ... } ... }
该命令应该写成 "\fn Foo::operator==(const Foo&, const Foo&)" 而不是自由函数 "\fn operator==(const Foo&, const Foo&)"。
如果不这样做，QDoc 无法解析该函数。
注意：\fn 命令是 QDoc 的默认命令：当在 QDoc 注释中找不到主题命令时，QDoc 会尝试将文档与下面的代码联系起来，就好像它是函数的文档一样。因此，如果函数的 QDoc 注释直接写在 .cpp 文件中函数实现的上方，则在记录函数时不需要包含此命令。但是当记录一个在 .cpp 文件中由 .h 文件实现的内联函数时，它必须存在。
/ *! \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. * /
QDoc 渲染后：
bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
Returns
trueif this toolbar is dockable in the given area; otherwise returnsfalse.
注意：在调试模式下运行（在调用 QDoc 之前使用 -debug 命令行选项或设置 QDOC_DEBUG 环境变量）可以帮助解决 QDoc 无法解析的 \fn 命令的问题。在调试模式下，可以获得额外的诊断信息。
参见 \overload。
\group
\group 命令创建一个单独的页面，列出属于该组的类。参数是组名。
使用 \ingroup 命令将类包含在组中。Overview 页面也可以使用相同的命令关联到一个组，但 Overview 页面列表必须使用 \generatelist 命令显式请求（参见下面的示例）。
\group 命令后面通常跟着 \title 命令和对该组的简短介绍。该组的 HTML 页面被写入到 <lower-case>group.html 中的 .html 文件中。
每个类名都作为指向类参考页面的链接列出，后跟类的 \brief 文本。
/ *! \group io \title Input/Output and Networking These classes are used to handle input and output to and from external devices, processes, files etc., as well as manipulating files and directories. * /
QDoc 在 io.html 中生成一个组页面，如下所示：
Input/Output and Networking
These classes are used to handle input and output to and from external devices, processes, files etc., as well as manipulating files and directories.
QAbstractSocket The base functionality common to all socket types QBuffer QIODevice interface for a QByteArray QClipboard Access to the window system clipboard
请注意，与组相关的概览页面必须使用带有 related 参数的 \generatelist 命令明确列出。
/ *! \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 和 \generatelist。
\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，如下所示：
<QtAlgorithms> - Generic Algorithms
The
header file provides generic template-based algorithms. More... Functions
- RandomAccessIterator qBinaryFind (RandomAccessIterator begin, RandomAccessIterator end, const T & value)
- ...
Detailed Description
The
header file provides generic template-based algorithms. Qt provides a number of global template functions in
<QtAlgorithms>that work on containers and perform well-know algorithms....
参见 \inheaderfile。
\macro
\macro 命令用于记录 C++ 宏。 参数是以下三种样式之一的宏：类似函数的宏，如 Q_ASSERT()，声明式的宏，如 Q_PROPERTY()，以及不带括号的宏，如 Q_OBJECT。
\macro 注释必须包含一个 \relates 命令，将宏注释附加到类、头文件或命名空间的。否则，文档就会丢失。以下是三个示例宏注释，后跟它们在 qtglobal.html 或 qobject.html 中的样子：
/ *! \macro void Q_ASSERT(bool test) \relates <QtGlobal> Prints a warning message containing the source code file name and line number if \a test is false. ... \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} * /
void Q_ASSERT ( bool test )
Prints a warning message containing the source code file name and line number if test is false.
...
See also Q_ASSERT_X(), qFatal() and Debugging Techniques.
/ *! \macro Q_PROPERTY(...) \relates QObject This macro declares a QObject property. The syntax is: ... \sa {Qt's Property System} * /
Q_PROPERTY ( ... )
This macro declares a QObject property. The syntax is:
...
See also Qt's Property System.
/ *! \macro Q_OBJECT \relates QObject The Q_OBJECT macro must appear in the private section of a class definition that declares its own signals and slots, or that uses other services provided by Qt's meta-object system. ... \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System} * /
Q_OBJECT
The Q_OBJECT macro must appear in the private section of a class definition that declares its own signals and slots or that uses other services provided by Qt's meta-object system.
...
See also Meta-Object System, Signals & Slots and Qt's Property System.
\module
\module 创建一个页面，列出属于命令参数指定的模块的类。通过在 \class 注释中包含 \inmodule 命令，将一个类列入模块。
\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. * /
QDoc 渲染 qtnetwork.html，如下所示：
Qt Network Module The Qt Network module offers classes that allow you to write TCP/IP clients and servers.More...
QAbstractSocket The base functionality common to all socket types ... ...
Detailed Description
The Qt Network module offers classes that allow you to write 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 命令来省略最后自动生成的类列表。
See also \inmodule
\namespace
\namespace 命令用于记录作为其参数命名的 C++ 命名空间的内容。QDoc 为命名空间生成的参考页面类似于它为 C++ 类生成的参考页面。
/ *! \namespace Qt \brief Contains miscellaneous identifiers used throughout the Qt library. * /
QDoc 渲染 qt.html，如下所示：
Qt Namespace
The Qt namespace contains miscellaneous identifiers used throughout the Qt library. More...
#include <Qt>Types
- flags Alignment
- ...
Detailed Description
Contains miscellaneous identifiers used throughout the Qt library.
...
请注意，在 C++ 中，一个特定的命名空间可以在多个模块中使用，但是当来自不同模块的 C++ 元素在同一个命名空间中声明时，命名空间本身必须仅记录在一个模块中。例如，上面示例中的命名空间 Qt 包含来自 QtCore 和 QtGui 的类型和函数，但它仅在 QtCore 中使用 \namespace 命令记录。
\page
\page 命令用于创建独立的文档页面。 参数可以由空格分隔的两部分组成。第一部分是 QDoc 应该存储页面的文件的名称。第二部分（如果存在）是指定页面类型的单词。目前，第二部分可以是以下单词列表之一：
- api —— 这是用于 C++ 类引用和 QML 类型引用的页面类型。你永远不应该在你写的页面上使用这个，因为这个是为 QDoc 保留的。
- attribution —— 描述（代码）归属的页面。
- example —— 描述工作示例的页面。
- faq —— 一个常见问题。
- howto —— 关于如何使用软件某些组件的用户指南。
- overview —— 用于提供一些重要主题概述的文本页面。
- tutorial —— 对于教程中的文本页面。
页面标题使用 \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() 宏定义属性。该宏将属性名称及其设置、重置和获取函数作为参数。
Q_PROPERTY(QString state READ state WRITE setState)
set、reset 和 get 函数不需要记录，记录属性就足够了。QDoc 将生成一个访问函数列表，该列表将出现在属性文档中，而属性文档又将位于定义该属性的类的文档中。
\property 命令注释通常包括一个 \brief 命令。对于属性，\brief 命令的参数是一个句子片段，将包含在属性的单行描述中。该命令遵循与 \variable 命令相同的 描述 规则。
/ *! \property QPushButton::flat \brief Whether the border is disabled. This property's default is false. * /
QDoc 将其包含在 qpushbutton.html 中，如下所示：
flat : bool
This property holds whether the border is disabled.
This property's default is false.
Access functions:
- bool isFlat () const
- void setFlat ( bool )
/ *! \property QWidget::width \brief The width of the widget excluding any window frame. See the \l {Window Geometry} documentation for an overview of window geometry. \sa geometry, height, size * /
QDoc 将其包含在 qwidget.html 中，如下所示：
width : const int
This property holds the width of the widget excluding any window frame.
See the Window Geometry documentation for an overview of window geometry.
Access functions:
- int width () const
\qmlattachedproperty
\qmlattachedproperty 命令用于记录将附加到某些 QML 类型的 QML 属性。请参阅 Attached Properties。论点是该行的其余部分。参数文本应该是属性类型，后跟声明属性的 QML 元素名称、:: 限定符，最后是属性名称。如果我们在 QML ListView 中有一个名为 isCurrentItem 的 QML 附加属性，并且该属性的类型为 bool，则它的 \qmlattachedproperty 将如下所示：
/ *! \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 的值类型。 参数是类型名称。该类型必须使用 \ingroup 命令包含在 QML 值类型 组中，如下所示。 这将导致 QDoc 在 QML 值类型页面上包含该类型的文档。\brief 命令也是必需的，因为它也出现在 QML 值类型 页面上。
/ *! \qmlvaluetype int \ingroup qmlvaluetypes \brief An integer is a whole number, for example 0, 10, or -20. An integer is a whole number, e.g. 0, 10, or -20. The possible \c int values range from around -2000000000 to around 2000000000, although most elements will only accept a reduced range (which they mention in their documentation). Example: \qml Item { width: 100; height: 200 } \endqml \sa {QML Value Types} * /
QDoc 将其输出为 qml-int.html。
\qmlclass
此命令已弃用。请改用 \qmltype。
\qmlclass 命令用于记录由 C++ 类实例化的 QML 类型。该命令有两个参数。第一个参数是 QML 类型的名称。第二个参数是实例化 QML 类型的 C++ 类的名称。
/ *! \qmlclass Transform QGraphicsTransform \ingroup qml-transform-elements \since 4.7 \brief Provides a way of building advanced transformations on Items. The Transform element is a base type which cannot be instantiated directly. The following concrete Transform types are available: \list \li \l Rotation \li \l Scale \li \l Translate \endlist The Transform elements let you create and control advanced transformations that can be configured independently using specialized properties. You can assign any number of Transform elements to an \l Item. Each Transform is applied in order, one at a time. * /
此示例生成 QML Transform 页面。\qmlclass 注释应该包括 \since 命令，因为所有 QML 类型都是新的。它还应该包括 \brief 命令。如果一个类型是一组 QML 类型的成员，它还应该包括一个或多个 \ingroup 命令。
\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 类型。该命令有一个参数，即 QML 类型的名称。
如果 QML 类型由 C++ 类实例化，则必须使用 \instantiates Context 命令指定该类。
/ *! \qmltype Transform \instantiates 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 注释包括 \instantiates，以指定 Transform 由 C++ 类 QGraphicsTransform 实例化。\qmltype 注释应始终包含 \since 命令，因为所有 QML 类型都是新的。它还应该包括一个 \brief 描述。如果 QML 类型是 QML 类型组的成员，则 \qmltype 注释应包含一个或多个 \ingroup 命令。
\qmlproperty
\qmlproperty 命令用于记录 QML 属性。论点是该行的其余部分。参数文本应该是属性类型，后跟 QML 类型名称、:: 限定符，最后是属性名称。如果我们在 QML 类型 Translate 中有一个名为 x 的 QML 属性，并且该属性的类型为 real，它的 \qmlproperty 将如下所示：
/ *! \qmlproperty real Translate::x The translation along the X axis. * /
QDoc 在 Translate 元素的 QML 参考页面上包含此 QML 属性。
如果 QML 属性是枚举类型，或者它包含标志的按位组合，则 \value 命令可用于记录可接受的值。
\qmlsignal
\qmlsignal 命令用于记录 QML 信号。论点是该行的其余部分。参数应该是：声明信号的 QML 类型、:: 限定符，最后是信号名称。如果我们有一个名为 clicked() 的 QML 信号，它的文档将如下所示：
/ *! \qmlsignal QtQuick::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-command。
A QML class can be associated with a module by adding the \inqmlmodule command to the comment-block that documents the class. You can link to any member of a QML module using the module name and two colons (::) prefix.
\beginqdoc
A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
\endqdoc
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 module，模块名称（不带版本号）作为唯一参数。组的每个成员都必须使用模块名称和两个冒号（::）链接到。
\qmltype ClickableButton
\inqmlmodule ClickableComponents
A clickable button that responds to the \c click() event.
要链接到 ClickableButton，请使用 \l ClickableComponents::ClickableButton 格式。
此处可以使用 \noautolist 命令来省略末尾自动生成的类型列表。
\instantiates
\instantiates 命令用于元素 QML 类型的 QML type 注释中，以指定实例化 QML 类型的 C++ 类的名称。
如果 QML 类型没有由 C++ 类实例化，则不使用此命令。
/ *! \qmltype Transform \instantiates 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 注释包括 \instantiates，以指定 Transform 由 C++ 类 QGraphicsTransform 实例化。
\typealias
\typealias 命令类似于 \typedef，但专门用于记录 C++ 类型别名：
class Foo { public: using ptr = void*; // ... }
这可以记录为
/*!
\typealias Foo::ptr
*/
QDoc 会在描述别名的文档中自动生成一句话：
This is a type alias for
void*.
\typealias 命令是在 QDoc 5.15 中引入的。
参见 \typedef。
\typedef
\typedef 命令用于记录 C++ typedef。参数是 typedef 的名称。 typedef 的文档将包含在声明 typedef 的类、命名空间或头文件的参考文档中。要将 \typedef 与类、命名空间或头文件相关联，\typedef 注释必须包含 \relates 命令。
/ *! \typedef QObjectList \relates QObject Synonym for QList<QObject>. * /
QDoc 将其包含在 qobject.html 中：
typedef QObjectList
另一个例子，虽然比较罕见：
/ *! \typedef QMsgHandler \relates QtGlobal This is a typedef for a pointer to a function with the following signature: \code void myMsgHandler(QtMsgType, const char *); \ endcode \sa QtMsgType, qInstallMessageHandler() * /
QDoc 在 qtglobal.html 中包含以下内容：
typedef QtMsgHandler
This is a typedef for a pointer to a function with the following signature:
void myMsgHandler(QtMsgType, const char *);See also QtMsgType and qInstallMessageHandler().
其他类型定义位于定义它们的类的参考页面上。
/ *! \typedef QList::Iterator Qt-style synonym for QList::iterator. * /
QDoc 在类 QList 的参考页面上包含这个：
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 * /
QDoc 将其包含在 qstyleoption.html 中：
QPalette QStyleOption::palette
This variable holds 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() * /
QDoc 在 qtreewidget.html 中包含以下内容：
const int QTreeWidgetItem::Type
The default type for tree widget items.
const int QTreeWidgetItem::UserType
The minimum value for custom types. Values below UserType are reserved by Qt.