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)
属性
属性文档位于读取函数实现的上方。属性的主题命令是 \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
属性文档通常以 "This property...（此属性...）"开头，但这是另一种表达方式：
- "此属性持有......"
- "此属性描述......"
- "此属性表示......"
- "当......时返回
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.
*/
© 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.
