文档分类

预定义的文档类别或类型主要有以下几种：

• 文章
• C++ API 文档
• QML 类型文档
• 代码示例

QDoc 能够根据类型对页面进行排版。此外，样式表还可以对各类别的显示提供额外的控制。

API 文档

QDoc 在根据一组源代码和 QDoc 注释中的文档来创建 API 文档方面表现出色。 具体来说，QDoc 了解 Qt 的架构，并能验证 Qt C++ 类、函数或属性的文档是否存在。如果 QDoc 无法将文档与代码实体关联，或者代码实体没有文档，它会发出警告和错误。

通常，每个 Qt 代码实体（如属性、类、方法、信号和枚举）都有相应的topic 命令。QDoc 将根据 C++ 命名规则将文档与源代码关联起来。

QDoc 会解析头文件（通常是.h 文件）以构建类结构树。然后，QDoc 会解析源文件和文档文件，将文档与类结构关联起来。之后，QDoc 将为该类生成一个页面。

语言风格

为了生成高质量的 API 文档，Qt API 参考手册遵循特定的语言规范。虽然本页内容演示了如何创建 API 文档，但风格指南则展示了参考资料如何保持语言使用的一致性。

• C++ 文档风格
• QML 文档风格

QML 类型的文档编写

在QML 领域中，还有其他需要进行文档记录的实体，例如 QML 信号、附加属性以及 QML 方法。虽然它们在内部使用 Qt 技术，但 QML API 文档在布局和命名约定方面与 Qt C++ API 文档有所不同。

QML 相关的 QDoc 命令列表：

• \qmlattachedmethod
• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - 生成 QML 类型的文档
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

要编写 QML 类型的文档，请先创建一个使用 \qmltype 作为主题命令。

QML 解析器

如果您的 QML 类型在qml文件中定义，请在该文件中为其编写文档。如果您的 QML 类型由一个 C++ 类表示，请在该 C++ 类的cpp文件中为其编写文档，并使用 \nativetype 命令来指定该 C++ 类的名称。如果 QML 类型是在qml文件中定义的，请不要在cpp文件中为其编写文档。

在qml文件中为 QML 类型编写文档时，请将每个 QDoc 注释放置在该注释所针对的实体正上方。例如，将包含 \qmltype 命令（主题注释）的 QDoc 注释，应直接置于qml文件中外部 QML 类型的正上方。用于文档化 QML 属性的注释应置于属性声明的正上方，QML 信号处理程序和 QML 方法的注释亦依此类推。请注意，在qml文件中文档化 QML 属性时，通常无需将 \qmlproperty 命令作为主题命令（在cpp文件中为 QML 类型编写文档时必须这样做），因为 QML 解析器会自动将每个 QDoc 注释与其解析到的下一个 QML 声明相关联。对于 QML 信号处理程序和 QML 方法的注释也是如此。但有时在注释中包含一个或多个 \qmlproperty 命令，例如当属性类型是另一个 QML 类型，且您希望用户仅使用该 QML 类型中的某些属性而非全部时。 但在为具有别名的属性编写文档时，请将相应的 QDoc 注释放置在别名声明的正上方。在这种情况下，QDoc 注释必须包含一个 \qmlproperty 命令，因为这是 QDoc 识别该别名属性类型的唯一方式。

在相应 C++ 类的cpp文件中（如果该类有 cpp 文件）为某个 QML 类型编写文档时，通常应将每个 QDoc 注释置于其所描述的实体正上方。 不过，QDoc 不会使用 QML 解析器来解析这些文件（而是使用 C++ 解析器），因此这些 QML QDoc 注释可以出现在cpp文件的任意位置。请注意，cpp文件中的 QML QDoc 注释必须使用QML 主题命令。也就是说， \qmltype 命令必须出现在该 QML 类型的 QDoc 注释中，而 \qmlproperty 命令必须出现在每个 QML 属性 QDoc 注释中。

QML 模块

一个 QML 类型属于一个模块。该模块可能包含某个平台的所有相关类型，也可能包含某个特定版本的 Qt Quick。例如，Qt Quick 2 的 QML 类型属于Qt Quick 2 模块，而对于 Qt 4 中引入的较旧类型，则另有Qt Quick 1 模块。

QML 模块允许对 QML 类型进行分组。 \qmltype topic 命令必须包含 \inqmlmodule context 命令，以将该类型与某个 QML 模块关联起来。同样地， \qmlmodule topic 命令必须存在于单独的.qdoc 文件中，以生成该模块的概述页面。概述页面将列出该 QML 模块中的 QML 类型。

因此，指向 QML 类型的链接也必须包含模块名称。例如，如果一个名为TabWidget 的类型位于UIComponents 模块中，则必须将其链接为UIComponents::TabWidget 。

只读和内部 QML 属性

QDoc 会检测标记为 `readonly` 的 QML 属性。请注意，该属性必须使用某个值进行初始化。

readonly property int sampleReadOnlyProperty: 0

不打算作为公共接口使用的属性和信号可以使用 \internal 命令进行标记。QDoc 不会在生成的输出中发布这些文档。

文章与概述

文章和概述是一种写作风格，最适合用于提供有关某个主题或概念的概要信息。它可以介绍一项技术，或讨论如何应用某个概念，但不会过多地详细讨论具体的操作步骤。 不过，此类内容可以作为读者的切入点，引导他们查找相关教学和参考资料，例如教程、示例和类文档。概述的一个例子可能是产品页面，例如对Qt Quick 的顶层讨论、各个模块、设计原则或工具。

要标明文档属于文章类型，需在\page 命令后添加 article 关键字：

/*!
    \page overview-qt-technology.html
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

“写作主题命令”一节列出了可用的\page 命令参数。

代码示例

示例是展示特定技术或概念实际应用的有效方式。就中间件而言，这通常表现为一个应用程序，其中包含简单的代码以及对代码功能的清晰说明。任何模块、API、项目、模式等都应至少有一个好的示例。

一个示例可能会附带一个教程。教程负责指导并描述代码，而代码示例则是用户可以学习的具体代码内容。代码示例中可能包含教程中未提及的说明性文字。

QDoc 将使用 \example 命令生成一个包含示例代码及说明的页面。

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc 将使用输入变量exampledirs中指定的目录来查找 Qt Project（.pro ）文件，从而生成示例文件。生成的 HTML 文件的文件名为declarative-ui-components-tabwidget.html 。QDoc 还将列出所有示例代码。