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 - 类的简短描述 (必须)
\since - 添加此类时的版本 (必须)
\internal - 将类标记为内部。内部类不会出现在公共 API 文档中。

简短和详细描述

“简短描述”使用 \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

属性文档通常以“此属性...”开头，但这些都是可选表达式。

"此属性持有..."
"此属性描述..."
"此属性表示..."
"当...返回true，当...返回false - 对于只读属性。"
"设置... - 对于配置类型的属性。"

属性文档必须包含以下内容

属性的描述和行为
属性的接受值
属性的默认值

类似于函数，默认类型可以链接或用\c命令标记。

值范围样式的示例是

值从0.0（无模糊）到最大半径（最大模糊）范围。默认情况下，属性设置为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.
*/