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
    \instantiates 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}

\instantiates 接受实现 QML 类型的 C++ 类作为参数。对于以 QML 实现的类型，这不是必需的。

简短描述 为 QML 类型提供一个摘要。简短描述无需是一个完整的句子，并且可以以动词开头。QDoc 将将简短描述附加到 QML 类型上，包括表和生成的列表。

\qmltype ColorAnimation
\brief Animates changes in color values

这里是简短语句的一些替代动词

"提供..."
"指定..."
"描述..."

详细描述 紧接简短描述，可能包含图像、代码片段以及链接到其他文档。

属性

属性描述侧重于属性做什么，并且可能使用以下样式

属性文档通常以 "此属性..." 开头，但对于某些属性，这些是常见的表达

"此属性包含..."
"此属性描述..."
"此属性代表..."
"当...返回 true 且当...返回 false 时" - 对于标记为 只读 的属性。
"设置..." - 对于配置类型的属性。

信号和处理器文档

QML 信号在网络文件中进行文档化，或者在 C++ 实现中使用 \qmlsignal 命令。信号文档必须包括发送信号的条件，提及相应的信号处理器，并文档化信号是否接受参数。

/*
    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 文件中函数实现的前面。函数的主题命令是 \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 枚举使用 \qmlproperty 命令作为 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++ 中实现，则文档可以链接到相应的 C++ 枚举。但是，QDoc 注释应建议枚举是一个 C++ 枚举。