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，类的文档可以被标记为 internal。

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 参数为 C++ 类实现的 QML 类型。对于在 QML 中实现的类型，这是不需要的。

简要描述 为 QML 类型提供了摘要。简要不需要是完整的句子，可以以动词开头。QDoc 将在表格和生成的列表中把简要描述附加到 QML 类型上。

 \qmltype ColorAnimation
 \brief Animates changes in color values

这里有一些简要陈述的备用动词：

  • "Provides..."
  • "Specifies..."
  • "Describes..."

详细说明 遵循简要，可能包含图像、snippet 和指向其他文档的链接。

Properties

属性描述的重点是该属性的 作用，可以使用以下风格：

属性文档通常以 "This property..." 开始，但对于某些属性，这些是常见的表达方式：

  • "This property holds..."
  • "This property describes..."
  • "This property represents..."
  • "Returns true when... and false when..." —— 对于标记为 read-only 的属性。
  • "Sets the..." —— 用于配置类型的属性。.

Signals 和 Handlers 文档

QML 信号在 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()

这些是可能的信号文档样式。

  • "This signal is triggered when..."
  • "Triggered when..."
  • "Emitted when..."

Methods 和 JavaScript 函数

通常，函数文档放在 .cpp 文件中函数的实现之前。函数的 主题命令 是 \fn。

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

 /*
     \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)

Some common verbs for function documentation:

  • "Copies..." —— 用于构造函数
  • "Destroys..." —— 用于析构函数
  • "Returns..." —— 用于 getter 函数

函数文档必须记录：

  • 返回类型
  • 参数
  • 函数的行为

\a 命令在文档中标记参数。返回类型的文档应链接到类型文档，或在布尔值的情况下用 \c 命令标记。

Enumerations

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++ 实现的，文档可以链接到相应的 C++ 枚举。但是，QDoc 注释应该提示该枚举是 C++ 枚举。

C++ 文档样式 ◦ 命令索引