QML 文档风格

QDoc 可以处理作为 C++ 类定义的 QML 类型，以及在.qml 文件中定义的 QML 类型。对于作为 QML 类型进行文档记录的 C++ 类，其 QDoc 注释位于.cpp 文件中；而直接在 QML 中定义的 QML 类型，其注释则位于.qml 文件中。此外，这些 C++ 类还必须使用 QML主题命令进行文档记录：

对于在.qml 文件中定义的 QML 类型，QDoc 将解析 QML 代码，并确定 QML 定义中的属性、信号和类型。此时，QDoc 代码块必须紧贴在声明的正上方。对于在 C++ 中实现的 QML 类型，如果 C++ 类的文档不存在，QDoc 将输出警告。如果该类文档不属于公共 API，则可将其标记为内部。

QML 类型

\qmltype 命令用于生成 QML 类型的文档。

    \qmltype TextEdit
    \nativetype QQuickTextEdit
    \inqmlmodule QtQuick
    \ingroup qtquick-visual
    \ingroup qtquick-input
    \inherits Item
    \brief Displays multiple lines of editable formatted text

    The TextEdit item displays a block of editable, formatted text.

    It can display both plain and rich text. For example:

    \qml
        TextEdit {
            width: 240
            text: "<b>Hello</b> <i>World!</i>"
            font.family: "Helvetica"
            font.pointSize: 20
            color: "blue"
            focus: true
        }
    \endqml

    \image declarative-textedit.gif

    ... omitted detailed description

    \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}

该 \nativetype 命令将实现该 QML 类型的 C++ 类作为参数。对于在 QML 中实现的类型，则无需此参数。

简要描述为 QML 类型提供概述。简要描述无需构成完整句子，且可以以动词开头。QDoc 会在表格和生成的列表中将简要描述附加到 QML 类型上。

\qmltype ColorAnimation
\brief Animates changes in color values

以下是简要描述中可选的动词：

“提供...”
“指定...”
“描述...”

详细描述紧随简要描述之后，可包含图片、代码片段以及指向其他文档的链接。

属性

属性描述侧重于该属性的功能，可采用以下格式：

属性文档通常以“此属性...”开头，但针对某些属性，常见表述如下：

“该属性包含……”
“该属性描述……”
“该属性表示……”
“当……时返回true ，当……时返回false ”——适用于标记为read-only 的属性。
“设置...”——适用于用于配置类型的属性。

信号与处理程序文档

QML 信号的文档记录在 QML 文件中，或在 C++ 实现中通过 \qmlsignal 命令在 C++ 实现中记录。信号文档必须包含触发信号的条件、提及相应的信号处理程序，并说明该信号是否接受参数。

/*
    This signal is emitted when the user clicks the button. A click is defined
    as a press followed by a release. The corresponding handler is
    \c onClicked.
*/
signal clicked()

信号的可能文档样式如下：

“当……时，此信号会被触发”
“在……时触发”
“在……时发出……”

方法和 QML 函数

通常，函数文档应紧接在.cpp 文件中该函数的实现代码之前。函数的topic命令为 \fn。对于 QML 中的函数，文档必须紧置于函数声明的上方。

函数文档以动词开头，表明该函数执行的操作。

/*
    \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)

    Deletes the content at \a index from the model.

    \sa clear()
*/
void QQuickListModel::remove(QQmlV8Function *args)

函数文档中的一些常用动词：

“复制...” — 用于构造函数
“销毁...” — 用于析构函数
“返回...” — 用于访问器函数

函数文档必须包含以下内容：

返回类型
参数
函数的操作

使用 \a 命令用于在文档中标记参数。对于布尔值，返回类型的文档应链接至类型文档，或使用 \c 命令进行标记。

枚举

QML 枚举通过 \qmlenum 命令记录为 QML 属性。请使用 \value 命令来记录枚举值。请为每个值添加类型名称作为前缀，并用句点 (.) 分隔，因为 QDoc 不会自动执行此操作。

/*!
\qmlproperty enumeration QtQuick2::Text::font.weight

Sets the font's weight.

The weight can be one of:
\value Font.Light
\value Font.Normal      The default
\value Font.DemiBold
\value Font.Bold
\value Font.Black

QDoc 注释中会列出枚举的各个值。

如果枚举是在 C++ 中实现的，请考虑使用 \qmlenumeratorsfrom 命令。如果无法使用该命令，文档也可以直接链接到相应的 C++ 枚举。不过，此时 QDoc 注释应注明该枚举是 C++ 枚举。

C++ 文档风格命令索引

© 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.