文档类别

有几种预定义的文档类别或类型：

• 操作指南
• 教程
• 概述
• 文章
• FAQ（常见问题）
• C++ API 文档
• QML 类型文档
• 代码示例

QDoc 能够根据类型对页面进行格式化。此外，样式表还能为每个类别的显示提供额外控制。

应用程序接口文档

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

一般来说，每个 Qt 代码实体（如属性、类、方法、信号和枚举）都有一个相应的主题命令。QDoc 会使用 C++ 命名规则将文档与源代码关联起来。

QDoc 将解析头文件（通常是.h 文件），以建立类结构树。然后，QDoc 将解析源文件和文档文件，将文档附加到类结构上。之后，QDoc 将为类生成一个页面。

语言风格

为了生成高质量的 API 文档，Qt API 参考资料遵循特定的语言指南。本页的内容演示了如何创建 API 文档，而风格指南则演示了参考资料如何使用一致的语言。

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

记录 QML 类型

在QML 的世界中，我们还需要记录其他实体，如 QML 信号、附加属性和 QML 方法。在内部，它们使用 Qt 技术，然而，QML API 文档需要不同于 Qt C++ API 文档的布局和命名约定。

与 QML 相关的 QDoc 命令列表：

• \附加属性
• \附加信号
• \QMLvaluetype
• \qmltype- 创建 QML 类型文档
• \方法
• \属性
• \qmlsignal
• \继承
• \qmlmodule
• \inqmlmodule
• \原生类型

要记录 QML 类型，首先要创建一个使用\qmltype命令作为主题命令的 QDoc 注释。

QML 解析器

如果你的 QML 类型定义在一个qml文件中，就在那里记录它。如果你的 QML 类型是由 C++ 类表示的，那就把它记录在 C++ 类的cpp文件中，并包含一个\nativetype命令来指定 C++ 类的名称。如果 QML 类型定义在qml文件中，就不要在cpp文件中记录 QML 类型。

在qml文件中记录 QML 类型时，把每个 QDoc 注释直接放在该注释适用的实体之上。例如，把包含\qmltype命令的 QDoc 注释（主题注释）放在qml文件中外部 QML 类型的正上方。把记录 QML 属性的注释放在属性声明的正上方，QML 信号处理程序和 QML 方法也是如此。请注意，在qml文件中记录 QML 属性时，通常不把\qmlproperty命令作为 topic 命令（在cpp文件中记录 QML 类型时必须这样做），因为 QML 解析器会自动把每个 QDoc 注释与它解析的下一个 QML 声明关联起来。QML 信号处理器和 QML 方法注释也是如此。但有时在注释中包含一个或多个\qmlproperty命令是有用的，例如，当属性类型是另一种 QML 类型，而你希望用户只使用该另一种 QML 类型中的某些属性，而不是所有属性时。但在记录一个有别名的属性时，应将其 QDoc 注释直接放在别名声明的上方。在这些情况下，QDoc 注释必须包含一个\qmlproperty命令，因为这是 QDoc 知道别名属性类型的唯一方法。

在相应 C++ 类（如果有的话）的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 Qml 4 中引入的旧类型还有一个Qt Quick 1 模块。

QML 模块允许对 QML 类型进行分组。\qmltype主题命令必须有\inqmlmodule上下文命令，才能将类型与 QML 模块相关联。同样，一个单独的.qdoc 文件中必须有一个\qmlmoduletopic 命令，以便为模块创建概览页。概览页将列出 QML 模块的 QML 类型。

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

只读和内部 QML 属性

QDoc 可检测标记为readonly 的 QML 属性。请注意，属性必须初始化为一个值。

readonly property int sampleReadOnlyProperty: 0

不用于公共接口的属性和信号可用\internal命令标记。QDoc 不会在生成的输出中发布文档。

文章和概述

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

要表示文档是一篇文章，可以在 \page 命令后加上文章关键字：

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

    \brief provides a technology never seen before.

*/

编写主题命令部分列出了可用的 \page 命令参数。

教程、操作方法、常见问题

教程、操作方法和常见问题解答都是指导性材料，它们向读者提供指导或规定。教程是指导读者循序渐进地学习某一概念或技术的内容。How-To 和 FAQ（常见问题）以解答常见问题的形式提供指导。How-To 和 FAQ 是为了便于参考而设计的，不一定以线性递进的方式呈现。

要创建这些类型，可通过向\page命令提供type 参数来标记页面。type 参数是第二个参数，文件名是第一个参数。

/*!
    \page altruism-faq.html
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

编写主题命令部分列出了可用的 \page 命令参数。

代码示例

示例是演示特定技术或概念的实际用法的有效方法。当涉及到中间件时，通常是以应用程序的形式，使用简单的代码并清楚地解释代码的作用。任何模块、应用程序接口、项目、模式等都应该至少有一个好的示例。

示例可能附有教程。教程对代码进行指导和描述，而代码示例则是用户可以学习的代码内容。代码示例可能有教程中没有的附带文本。

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 还将列出所有示例代码。