主题命令
主题命令告诉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" | \module |
| 示例 | 项目名称，由项目配置变量提供，后面跟着一个连字符。 | "-example" | \example |
| QML类型 | QML的输出前缀，由outputprefixes配置变量提供。 如果包含此类型的模块被QDoc所知，则会添加模块名称作为前缀，后面跟着由outputsuffixes配置变量定义的QML输出后缀和一个连字符。 | 无 | \qmltype |
\class
\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命令，以及一个\brief描述。以下是一个非常简单的示例
/*!
\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文件。
\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).
*/注意包含命名空间限定符。
有关更多信息，请参阅\value和\omitvalue。
\example
\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
\externalpage 命令为外部 URL 分配一个标题。
/*!
\externalpage https://doc.qt.ac.cn/
\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 {https://doc.qt.ac.cn/}{Qt Documentation Site}
you can find the latest documentation for Qt, Qt Creator, the Qt SDK
and much more.
*/\externalpage 命令使维护文档更加容易。如果地址发生变化，只需更改 \externalpage 命令的参数即可。
\fn (函数)
\fn 命令用于记录一个函数。参数是函数的签名，包括其模板参数（如果有）、返回类型、const-ness 以及带类型的正式参数的列表。如果命名的函数不存在，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 文件中的函数实现上方时，通常不需要包含此命令。但必须在记录在 .h 文件中实现的 .cpp 文件中的内联函数时使用此命令。
/*!
\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.
*/注意：以调试模式运行（传递 -debug 命令行选项或在调用 QDoc 之前设置 QDOC_DEBUG 环境变量）可以帮助调试 QDoc 失败解析的 \fn 命令。在调试模式下，可提供额外的诊断信息。
另请参阅 \overload。
\group
\group 命令创建一个单独的页面，列出属于命名组的类、页面或其他实体。参数是组名。
通过使用 \ingroup 命令可以将类包含在组中。概述页面也可以使用相同的命令与组相关联，但必须显式使用 \generatelist 命令请求概述页面的列表（请参见下面的示例）。
\group命令通常后跟一个
.html文件中。
组中的每个实体都作为超链接列出（使用页面标题或类名），后面跟着实体文档中
/*!
\group io
\title Input/Output and Networking
*/QDoc生成一个组页面io.html。
注意，与组相关的概述页面必须专门使用带有
/*!
\group architecture
\title Architecture
These documents describe aspects of Qt's architecture
and design, including overviews of core Qt features and
technologies.
\generatelist{related}
*/另请参阅
\headerfile
.html文件中。
在头文件中被文档化的函数、类型或宏的文档，使用
如果参数作为头文件不存在，\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。
另请参阅\
\macro
\module
\module在指定命令的参数创建具有模块所属类列表的页面。包含一个包含于模块中的inmodule命令在类注释中。
\module命令通常后跟一个