文档类别

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

• How-To's
• Tutorial
• Overview
• Article
• FAQ (Frequently Asked Questions)
• C++ API 文档
• QML 类型文档
• Code Example

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

API 文档

在给定源码或 QDoc 注释时，QDoc 创建 API 文档表现出色。具体来说，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 命令列表：

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype - creates a QML type documentation
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \instantiates

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

QML 解析器

如果您的 QML 类型在 qml 文件中定义，请在此处记录。如果您的 QML 类型由 C++ 类表示，请将其记录在该 C++ 类的 cpp 文件中，并包含一个 \instantiates 命令来指定 C++ 类的名称。如果 QML 类型是在 qml 文件中定义的，则不要在 cpp 文件中记录 QML 类型。

在 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 文件中记录 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 Quick 1 模块也用于 Qt 4 中引入的旧类型。

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

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

只读和内部 QML 属性

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

 readonly property int sampleReadOnlyProperty: 0

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

Article & Overview

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

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

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

     \brief provides a technology never seen before.

 */

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

Tutorials, How-To's, FAQ

Tutorials、How-To's 和 FAQ 都是教学材料，因为它们向读者提供指导或规定。教程旨在引导读者逐步学习概念或技术的内容。 How-To 和 FAQ（常见问题）是以回答常见问题的形式来提供指导。操作方法和常见问题解答旨在便于参考，不一定以线性顺序呈现。

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

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

     \brief All the questions about altruism, answered.

     ...
 */

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

Code Examples

示例是展示某项技术或概念的实际应用的有效方式。 当涉及到中间件时，通常采用应用程序的形式，使用简单的代码并清楚地解释代码在做什么。 任何模块、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 项目文件（.pro）以生成示例文件。生成的 HTML 将有一个文件名：declarative-ui-components-tabwidget.html。QDoc 也将列出所有的示例代码。