文档类别

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

如何做
教程
概览
文章
Faq（常见问题解答）
C++ API 文档
QML 类型文档
代码示例

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

API 文档

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

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

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

注意：QDoc 使用头文件来了解类，并且不会正确处理头文件中的 QDoc 注释。

语言样式

为了制作高质量的 API 文档，Qt API 参考应遵循特定的语言指南。虽然本页演示了如何创建 API 文档，但风格指南演示了参考资料如何遵循一致的用语。

QML 类型的文档化

在 QML 的世界里，我们需要记录额外的实体，例如 QML 信号、附加属性和 QML 方法。尽管它们在内部使用 Qt 技术，但 QML API 文档需要与 Qt C++ API 文档不同的布局和命名约定。

QML 相关 QDoc 命令列表

注意：记得通过在文件扩展名变量中包含 *.qml 文件类型来启用 QML 解析。

要记录一个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注释中，并且在每个QML属性QDoc注释中必须出现一个\qmlproperty命令。

QML模块

一个QML类型属于一个模块。该模块可能包括一个平台的所有相关类型，或包含Qt Quick的某个版本。例如，Qt Quick 2的QML类型属于Qt Quick 2模块，同时还有一个Qt Quick 1模块用于在Qt 4中引入的旧类型。

QML模块允许对QML类型进行分组。必须有一个\qmltype主题命令和一个\inqmlmodule上下文命令来关联类型与QML模块。同样，必须在一个单独的.qdoc文件中包含\qmlmodule主题命令来创建模块的概览页面。概览页面将列出QML模块的QML类型。

因此，QML类型的链接也必须包含模块名称。例如，如果名为TabWidget的类型位于UIComponents模块中，它必须链接为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 命令参数。

教程、如何操作、FAQ

教程、如何操作和 FAQ 都是教学材料，因为它们指导或建议读者。教程是为指导读者沿着一个逐步学习路径学习一个概念或技术而设计的。如何操作和 FAQ（常见问题解答）通过提出常见问题的答案的形式提供指导。如何操作和 FAQ 为方便引用而设计，不一定按线性顺序展示。

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

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

    \brief All the questions about altruism, answered.

    ...
*/

编写主题命令部分列出了可用的 \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 项目（.pro）文件以生成示例文件。生成的 HTML 将有文件名，declarative-ui-components-tabwidget.html。QDoc 还将列出所有示例代码。

注意：示例的项目文件必须与目录名相同。

编写文档如何解决 QDoc 警告