C++ 文档风格
为了生成文档，QDoc 会遍历源代码，并为类等 C++ 类型生成文档。随后，QDoc 会将成员函数、属性及其他类型与相应的类关联起来。
请注意，文档必须位于实现文件中，例如.cpp 。
类文档
类文档是通过 \class 命令并以类名为第一个参数来生成。
/*!
\class QCache
\brief The QCache class is a template class that provides a cache.
\ingroup tools
\ingroup shared
\reentrant
QCache\<Key, T\> defines a cache that stores objects of type T
associated with keys of type Key. For example, here's the
definition of a cache that stores objects of type Employee
associated with an integer key:
\snippet code/doc_src_qcache.cpp 0
Here's how to insert an object in the cache:
\snippet code/doc_src_qcache.cpp 1
... detailed description omitted
\sa QPixmapCache, QHash, QMap
*/上下文命令会添加有关该类的信息，例如其模块或该类被添加的版本。
一些常见的上下文命令包括：
简要描述与详细描述
简要描述使用 \brief 命令标记，用于概括类的用途或功能。对于 C++ 类，QDoc 会自动提取类信息并生成注释。这些注释信息将以列表和表格的形式呈现，用于展示该类。
C++ 的简要描述应以以下内容开头：
"The <C++ class name> class"详细描述部分紧随简要描述之后。它提供了关于该类的更多信息。详细描述中可以包含图片、代码片段或指向其他相关文档的链接。简要描述与详细描述之间必须用空行分隔。
成员函数
通常，函数文档紧接在.cpp 文件中该函数的实现代码之前。对于未紧接在实现代码上方的函数文档，需要使用 \fn 。
/*!
\fn QString &QString::remove(int position, int n)
Removes \a n characters from the string, starting at the given \a
position index, and returns a reference to the string.
If the specified \a position index is within the string, but \a
position + \a n is beyond the end of the string, the string is
truncated at the specified \a position.
\snippet qstring/main.cpp 37
\sa insert(), replace()
*/
QString &QString::remove(int pos, int len)函数文档应以动词开头，说明该函数执行的操作。这同样适用于构造函数和析构函数。
函数文档中常用的动词包括：
- “构造...” — 用于构造函数
- “销毁...”——用于析构函数
- “返回...” — 用于访问器函数
函数文档必须说明：
- 返回类型
- 参数
- 函数的操作
使用 \a 命令用于在文档中标记该参数。对于布尔值，返回类型的文档应链接至类型文档，或使用 \c 命令进行标记。
/*!
Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
\sa scroller()
*/
bool QScroller::hasScroller(QObject *target)属性
属性文档应紧邻 read 函数的实现代码上方。属性的topic 命令为 \property。
/*!
\property QVariantAnimation::duration
\brief the duration of the animation
This property describes the duration in milliseconds of the
animation. The default duration is 250 milliseconds.
\sa QAbstractAnimation::duration()
*/
int QVariantAnimation::duration() const属性文档通常以“此属性...”开头，但也有以下替代表达方式：
- “该属性表示……”
- “该属性描述……”
- “该属性表示……”
- “当……时返回
true，当……时返回false”——适用于可读属性。 - “设置...”——适用于用于配置类型的属性。
属性文档必须包含：
- 属性的描述和行为
- 该属性允许的取值
- 属性的默认值
与函数类似，默认类型可通过\c 命令进行关联或标记。
值范围样式的示例如下：
取值范围从 0.0（无模糊）到 maximumRadius（最大模糊）。默认情况下，该属性设置为 0.0（无模糊）。
信号、通知器和槽
信号、通知器和槽的主题命令是 \fn。信号文档通常说明其触发或发射的条件。
/*!
\fn QAbstractTransition::triggered()
This signal is emitted when the transition has been triggered (after
onTransition() has been called).
*/信号文档通常以“当……时，此信号会被触发”开头。以下是其他写法：
- “当……时，此信号会被触发”
- “当……时触发”
- “在……时发出”
对于插槽或通知器，应记录其被信号触发或执行时的条件。
- “在……时执行”
- “该插槽在……时被执行”
对于具有重载信号的属性，QDoc 会将重载的通知器归类在一起。若要引用通知器或信号的特定版本，只需提及该属性，并说明该通知器存在不同版本即可。
/*!
\property QSpinBox::value
\brief the value of the spin box
setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/枚举、命名空间及其他类型
枚举、命名空间和宏在文档中都有相应的主题命令：
这些类型的语言风格应首先说明其为枚举或宏，随后进行类型描述。
对于枚举， \value 命令用于列出枚举值。QDoc 会为该枚举生成一个值表。
/*!
\enum QSql::TableType
This enum type describes types of SQL tables.
\value Tables All the tables visible to the user.
\value SystemTables Internal tables used by the database.
\value Views All the views visible to the user.
\value AllTables All of the above.
*/© 2026 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.
