主题命令
主题命令告诉 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 模块 | 无 | "-qmlmodule" | \Qmlmodule |
| 模块 | 无 | "-module" （模块 | \模块 |
| 示例 | 项目配置变量给出的项目名称，后接连字符。 | "-example" （示例 | \example |
| QML 类型 | 输出前缀（outputprefixes）配置变量给出的 QML 输出前缀。 如果 QDoc 已知包含此类型的模块，则模块名称会被添加为前缀，然后是 QML 输出后缀（由outputsuffixes 配置变量和连字符定义）。 | 无 | \qmltype |
\类
\class 命令用于记录 C++类、C/C++结构体或联合体。参数是类的完整限定名称。该命令告诉 QDoc 类是公共 API 的一部分，并允许你输入详细的描述。
/*!
\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命令以及一个简要说明。下面是一个非常简单的例子：
/*!
\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 呈现这个类的方式取决于你的style.css 文件。
\类
\enum 命令用于记录 C++ 枚举类型。参数是枚举类型的全名。
枚举值使用\value命令记录在 \enum 注释中。如果枚举值没有用 \value 记录，QDoc 会发出警告。可以使用\omitvalue命令来告诉 QDoc 不应记录某个枚举值，从而避免这些警告。枚举文档将包含在定义了枚举类型的类引用页、头文件页或命名空间页中。例如，考虑 Qt XML 命名空间中的枚举类型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 命令用于记录一个示例。参数是示例的路径，相对于 QDoc 配置文件中exampledirs变量列出的路径之一。
文档页面将输出为modulename-path-to-example.html。除非使用了\noautolist命令或为项目定义了配置变量url.examples，否则 QDoc 会在页面末尾添加一个包含所有示例源文件和图像文件的列表。
例如，如果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命令为外部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.
*/
如果不使用 \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 命令用于记录函数。参数是函数的签名，包括它的模板参数（如果有）、返回类型、常量和带有类型的形式参数列表。如果命名的函数不存在，QDoc 会发出警告。
该命令接受auto 作为函数的类型，尽管 QDoc 可以推断出函数的完整类型。在某些情况下，最好使用auto而不是函数的实际类型。在 \fn-command 中使用auto 作为返回类型，可以让作者明确地这样做，也适用于没有使用auto关键字定义的类型。
自 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 之前，通过-debug 命令行选项或设置QDOC_DEBUG 环境变量）有助于排除 QDoc 无法解析的 \fn 命令。在调试模式下，可以获得更多诊断信息。
另请参见 \overload。
\组
group）命令会创建一个单独的页面，列出属于某个命名组的类，页面或其他实体。参数是组名。
使用\ingroup命令可以将一个类包含在一个组中。概览页也可以使用相同的命令与组相关联，但概览页列表必须使用\generatelist命令明确请求（见下面的示例）。
在 \group 命令之后通常会有一个\title命令和一个简短的组介绍。组的 HTML 页面会被写入一个名为 <lower-case-group-name>.html 的.html 文件。
组中的每个实体都以链接的形式列出（使用页面标题或类名称），之后是实体文档中\brief命令的说明。
/*!
\group io
\title Input/Output and Networking
*/
QDoc 会生成一个组页面io.html 。
请注意，必须使用带有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、\annotatedlist、\generatelist 和 \noautolist。
\头文件
\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 命令用于记录 C++ 宏。参数是三种风格之一的宏：函数式宏，如Q_ASSERT() ；声明式宏，如Q_PROPERTY() ；不带括号的宏，如Q_OBJECT 。
macro注释必须包含一条\relates命令，将宏注释附加到类、头文件或命名空间中。否则，文档将丢失。
\模块
\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.
*/
这里可以使用\noautolist命令来省略最后自动生成的类列表。
另请参见\inmodule
\名称空间
\namespace 命令用于记录作为其参数命名的 C++ 命名空间的内容。QDoc 为命名空间生成的引用页与它为 C++ 类生成的引用页类似。
/*!
\namespace Qt
\brief Contains miscellaneous identifiers used throughout the Qt library.
*/
请注意，在 C++ 中，一个特定的命名空间可以在多个模块中使用，但当来自不同模块的 C++ 元素在同一命名空间中声明时，命名空间本身必须只在一个模块中记录。例如，上例中的命名空间 Qt 包含了QtCore 和QtGui 中的类型和函数，但使用 \namespace 命令只在QtCore 中进行了记录。
\页面
\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 命令用于记录 Qt 属性。参数是完整的属性名称。
属性使用Q_PROPERTY() 宏定义。该宏的参数包括属性名称及其 set、reset 和 get 函数。
Q_PROPERTY(QString state READ state WRITE setState)
设置、重置和获取函数无需记录，记录属性即可。QDoc 将生成一个访问函数列表，该列表将出现在属性文档中，而属性文档又将出现在定义该属性的类的文档中。
\property 命令注释通常包括一个\brief命令。对于属性来说，\brief 命令的参数是一个句子片段，它将包含在属性的一行描述中。该命令的描述规则与\variable命令相同。
/*!
\property QPushButton::flat
\brief Whether the border is disabled.
This property's default is false.
*/
\附加属性
\qmlattachedproperty 命令用于记录附加到某个 QML 类型的 QML 属性。见Attached Properties（附加属性）。参数是该行的其余部分。它必须以属性类型开头，然后是声明属性的 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 参考页面上包含了这个附加属性。
注意： 和\qmlproperty 一样，\qmlattachedproperty 也接受 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 参考页面上包含了该文档。
注意： 和\qmlproperty 一样，\qmlattachedsignal 也接受 QML 模块标识符作为参数的一部分。
\qmlvaluetype
\qmlvaluetype 命令用于记录 QML 的值类型。该命令只接受一个类型名称作为参数。
\qmlvaluetype 在功能上与（qmltype）命令相同。唯一不同的是，该类型将作为QML 值类型被命名（和分组）。
\qmlclass
该命令已被弃用。请使用\qmltype代替。
\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++ 类，你可以用 \nativetypecontext 命令指定该类。
\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注释应该总是包括一个since命令，因为所有的QML类型都是新的。它还应该包括一个简短的描述。如果一个 QML 类型是 QML 类型组的成员，那么 \qmltype 注释应该包括一个或多个\ingroup命令。
\qmlproperty
qmlproperty 命令用于记录 QML 属性。参数是该行的其余部分。参数文本应该是属性类型，然后是 QML 类型名称、:: 限定符，最后是属性名称。如果我们有一个名为x 的 QML 属性，它的 QML 类型是Translate ，而该属性的类型是real ，那么它的\qmlproperty 命令将如下所示：
/*!
\qmlproperty real Translate::x
The translation along the X axis.
*/
QDoc 在Translate 类型的 QML 参考页面上包含了这个 QML 属性。
如果 QML 属性是枚举类型的，或者它持有一个按位排列的标志组合，\value命令可以用来记录可接受的值。
QDoc 也接受完全限定的属性名，包括 QML 模块标识符：
\qmlproperty bool QtQuick.Controls::Button::highlighted
如果指定了，模块标识符（如上，QtQuick.Controls ）必须与相关的 \qmltype 文档中传递给\inqmlmodule命令的值相匹配。如果属性所属的 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 参考页面上。
注意： 和\qmlproperty 一样，\qmlsignal 也接受 QML 模块标识符作为参数的一部分。
\qmlmodule
使用\qmlmodule 命令创建QML 模块页。QML 模块页是 QML 类型或任何相关材料的集合。该命令需要一个可选的<VERSION> 编号参数，与group-command 类似。
把\inqmlmodule命令加到记录 QML 类型的注释块中，QML 类型就与模块相关联了。你可以用模块名和两个冒号（:: ）前缀链接到 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
在\qmltype主题中插入 \inqmlmodule 命令，QML 类型就会被标记为在特定 QML 模块导入下可用。该命令的唯一参数是模块（导入）名称，不含版本号。
QML 模块名称必须与用（\qmlmodule命令）记录的 QML 模块相匹配。
/*!
\qmltype ClickableButton
\inqmlmodule ClickableComponents
A clickable button that responds to the \c click() event.
*/
QDoc 会在 QML 类型参考页面顶部的表格中输出一行导入语句：import <qmlmodule>。
链接到 QML 类型时，QML 模块标识符可能会出现在链接目标中。例如
\l {ClickableComponents::}{ClickableButton}
链接到类型参考页面，链接文本为ClickableButton。
\说明
自 Qt 6.8 起，instantiates 命令已被弃用。请使用 \nativetype代替。
\原生类型
命令必须与 \qmltypetopic 命令一起使用。该命令的参数是一个 C++ 类。如果 QDoc 无法找到该 C++ 类，它会发出警告。该命令在 Qt 6.8 中引入。
使用 \nativetype-command 命令指定该类型在 C++ 中的名称。这将确保 QML 类型文档中生成的必要条件块包含一个 "In C++"条目。C++ 类将有相应的 "In QML "条目。
任何一个 QML 类型只能有一个本地类型。如果发生重新定义，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 命令与\typedef 类似，但专门用于记录 C++ 类型别名：
class Foo { public: using ptr = void*; // ... }
可以记录为
/*!
\typealias Foo::ptr
*/
QDoc 5.15 中引入了 \typealias 命令。
另请参见 \typedef。
\typedef
\typedef 命令用于记录 C++ 类型定义。参数是类型定义的名称。类型定义的文档将包含在声明类型定义的类、命名空间或头文件的参考文档中。要将\typedef 与类、名称空间或头文件相关联，\typedef 注释必须包含\relates命令。
/*!
\typedef QObjectList
\relates QObject
Synonym for QList<QObject>.
*/
其他类型定义位于定义它们的类的引用页中。
/*!
\typedef QList::Iterator
Qt-style synonym for QList::iterator.
*/
另请参见 \typealias。
\变量
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()
*/
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
