Back to Qt.io
Contact Us Blog Download Qt

C++ 文档样式命令索引

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 实现的类型，不需要这样做。

简要说明（brief description）是 QML 类型的摘要。简介不需要是一个完整的句子，可以以动词开头。QDoc 会在表格和生成的列表中将简要说明附加到 QML 类型上。

\qmltype ColorAnimation
\brief Animates changes in color values

下面是一些用于简要说明的备用动词：

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

详细描述紧跟简述，可能包含图片、片段和其他文档链接。

属性

属性描述的重点是属性的作用，可使用以下样式：

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

  • "此属性持有......"
  • "此属性描述......"
  • "此属性表示......"
  • "当......时返回true ，当......时返回false "- 对于标有read-only 的属性。
  • "设置......"- 用于配置类型的属性。

信号和处理程序文档

QML 信号可以在 QML 文件中记录，也可以用\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 文件中函数的实现之前。函数的主题命令是 \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 属性。属性的类型是enumeration 。使用\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++ 文档样式命令索引

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