QDoc 简介

QDoc 是 Qt 开发人员用于生成软件项目文档的工具。它通过从项目源文件中提取QDoc 注释，并将这些注释格式化为 HTML 页面或 DocBook XML 文档来工作。 QDoc会在.cpp 文件和.qdoc 文件中查找QDoc注释。QDoc不会在.h 文件中查找QDoc注释。QDoc注释总是以感叹号 (!) 开头。例如：

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

根据上面的 QDoc 注释，QDoc 会生成 HTML 页面QObject class reference 。

本手册介绍了如何在 QDoc 注释中使用 QDoc 命令，将完善的文档嵌入到您的源文件中。此外，还介绍了如何创建QDoc 配置文件，您可以在命令行中将其传递给 QDoc。

运行 QDoc

QDoc 程序的名称为qdoc 。要在命令行上运行 QDoc，请指定一个配置文件的名称：

$ ../../bin/qdoc ./config.qdocconf

QDoc 将.qdocconf 后缀识别为QDoc 配置文件。在配置文件中，您需要告知 QDoc 项目源文件、头文件以及.qdoc 文件的位置。此外，您还需在此指定 QDoc 应生成何种格式的输出（HTML、DocBook XML 等），以及生成的文档应保存到何处。 配置文件还包含供 QDoc 使用的其他信息。

有关如何设置 QDoc 配置文件的说明，请参阅《QDoc 配置文件》。

QDoc 的工作原理

QDoc首先读取您在命令行中指定的配置文件。它会将配置文件中的所有变量存储起来，以备后用。 它首先使用的变量之一是outputformats 。该变量用于告知 QDoc 将运行哪些输出生成器。默认值为HTML，因此如果您在配置文件中未设置outputformats ，QDoc 将生成 HTML 输出。这通常正是您所需要的，但您也可以指定DocBook以获得 DocBook 输出。

接下来，QDoc 会使用headerdirs变量和/或headers变量的值，来查找并解析项目中的所有头文件。 QDoc不会在头文件中扫描 QDoc 注释。它会解析头文件以构建一个主树，其中包含所有应被文档化的项目，换言之，即 QDoc 应为其查找 QDoc 注释的项目。

在解析完所有头文件并构建了待文档化的项目主树之后，QDoc 会使用 `sourcedirs` 变量和/或`sources` 变量的值，来查找并解析项目中的所有 `.cpp ` 和 `.qdoc ` 文件。这些就是 QDoc 会扫描以查找QDoc 注释的文件。 请记住，QDoc 注释以感叹号/*!开头。

对于找到的每个 QDoc 注释，它都会在主树中搜索该文档所属的项目。然后，它会解析注释中的 QDoc 命令，并将解析后的命令和注释文本存储在该项目的树节点中。

最后，QDoc 会遍历主树。对于每个节点，如果该节点存储了文档，QDoc 会调用由outputformats 变量指定的输出生成器，对文档进行格式化，并将其写入配置文件中outputdir变量指定的目录中。

命令类型

QDoc 解析三种类型的命令：

• 主题命令
• 上下文命令
• 标记命令

主题命令用于标识您正在编写文档的元素，例如 C++ 类、函数、类型，或者未映射到底层 C++ 元素的额外文本页面。

上下文命令用于告知 QDoc 正在文档化的元素与其他已文档化元素之间的关系，例如前后页面链接、页面组的包含关系，或库模块。 上下文命令还可以提供 QDoc 无法从源文件中获取的关于被文档化的元素的信息，例如，该元素是否线程安全、是否为重载或重新实现的函数，或者是否已被弃用。

标记命令用于告知 QDoc 文档中文本和图像元素应如何呈现，或说明文档的大纲结构。