QDoc简介

QDoc 手动 命令索引 ◦

内容

• 运行 QDoc
• 在单一执行模式下运行 QDoc
• QDoc 如何工作
• 命令类型

QDoc 简介

QDoc 是 Qt Developers 用于生成软件项目文档的工具。它的工作原理是从项目源文件中提取 QDoc 注释 ，然后将这些注释格式化为 HTML 页面或 DITA XML 文档。QDoc 在 .cpp 文件和 .qdoc 文件中查找 QDoc 注释。QDoc 不会在 .h 文件中查找 QDoc 注释。QDoc 注释始终以感叹号（ ！ ）开头。例如：

      /  * ！
          \ class  QObject 
          \ brief QObject 类是所有 Qt 对象的基类。  

          \ ingroup objectmodel

          \折返

          QObject 是  Qt \ l {Object Model}的核心。该该模型的
          中心特征是一种非常强大的无缝对象通信机制
           ，称为\ l { signals 和
           slots } 。您可以使用 connect() 将信号连接到插槽
          并断开与 disconnect() 的连接。避免
          永不结束通知循环，你可以暂时阻止
          使用 blockSignals() 发出信号。该保护功能
          connectNotify() 和 disconnectNotify() 使它成为可能
          跟踪连接。

          QObjects 在\ l {Object Trees ＆ 
          Ownership} {object trees}中组织自己。当你创建一个 QObject 的 用
          另一个对象作为父对象，该对象将自动进行
          将自己添加到父级的\ c children() 列表中。父母
          取得对象的所有权。它会自动
          在析构函数中删除它的子节点。你可以找一个
          对象按名称和可选的类型使用 findChild() 或
          findChildren()。

          每个对象都有一个 objectName()，其类名可以是
          通过相应的 metaObject() 找到（参见
          QMetaObject ::类名()）。你可以确定是否
          object 的类 
          通过使用 \ c inherits() 函数继承 QObject 继承层次结构中的另一个类。  

      。。。。
  *  /

从上面的 QDoc 注释中，QDoc 生成 HTML QObject 类参考 页面。

本手册介绍了如何在 QDoc 注释中使用 QDoc 命令在源文件中嵌入良好的文档。它还解释了如何制作 QDoc 配置文件 ，您将在命令行上传递给 QDoc。

运行 QDoc

QDoc 程序的名称是 qdoc 。要从命令行运行 qdoc，请为其指定配置文件的名称：

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

QDoc 将 .qdocconf 后缀识别为 QDoc 配置文件 。您可以在配置文件中告诉 QDoc 在哪里可以找到项目源文件，头文件和 .qdoc 文件。您还可以告诉 QDoc 要生成哪种输出（HTML，DITA XML，...），以及放置生成的文档的位置。配置文件还包含 QDoc 的其他信息。

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

在单一执行模式下运行 QDoc

从 Qt 5.5 开始，一种运行 QDoc 的新方法可以将生成 Qt5 文档所需的时间减少多达 90％。运行 QDoc 的新方法是 单执行 模式。Qt5 构建系统目前不提供单一执行模式，该系统仍使用 标准 模式。单一执行模式仅在您自己运行 QDoc 时可用，在您记录模块并将文档与其他 Qt 模块集成时，您通常需要这样做。

要在单一执行模式下运行 QDoc，请添加 -single-exec 到命令行并向 QDoc 传递一个主 qdocconf 文件，该文件只是所有 Qt5 模块的 qdoc​​conf 文件的文件路径列表。例如：

  /用户/我/ QT5 / qtbase /斌/的 QDoc
 - outputdir /用户/我/ QT5 / qtbase / DOC
 - INSTALLDIR /用户/我/ QT5 / qtbase / DOC /用户/我/ QT5 /主。qdocconf
 - single - exec

qdocconf 文件 master.qdocconf 只列出了要处理的所有 Qt5 模块的 qdoc​​conf 文件：

  /Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf
  /Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf
  /Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf
  /Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf
  /Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf
  /Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf
  /Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf
  /Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf
  /Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf
  /Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf
  /Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf
  /Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf
  /Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf
  /Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf
  /Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf
  /Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf
  /Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf
  /Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf
  /Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf
  /Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf
  /Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf
  /Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf
  /Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf
  /Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf
  /Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf
  /Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf
  /Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf
  /Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf
  /Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf
  /Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf
  /Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf
  /Users/me/qt5/qtimageformats/src/imageformats/doc/qtimageformats.qdocconf
  /Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf
  /Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf
  /Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf
  /Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf
  /Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf

为什么标准模式很慢

目前，Qt5 构建系统不使用 QDoc 的 单一执行 模式来生成 Qt5 文档。它在 标准 模式下运行 QDoc 。标准模式的出现是因为它是转换 Qt4 QDoc 以处理 Qt5 中 Qt 模块化的最简单方法。在 Qt4 中，QDoc 在所有 Qt4 源上运行一次，以生成 Qt 的 HTML 文档。在生成 Qt 文档时，Qt4 QDoc 还为 Qt 生成了一个 索引文件 。该索引文件旨在用作后续 QDoc 运行的输入，以便为基于 Qt 的其他软件库/产品生成 HTML 文档。Qt 索引文件允许 QDoc 将为其他库/产品编写的文档链接到 Qt4 文档。

当 Qt5 出现时，Qt 被分成了模块。从那以后，许多新模块被添加到 Qt。从版本 5.5 开始，Qt5 中有 40 多个独立的模块，每个模块都有自己的文档，链接到（取决于）其他 Qt 模块的文档。

在 标准模式下 ，QDoc 为每个模块运行两次。第一个 QDoc 运行特定的 Qt 模块，解析所有模块的源文件，然后使用该信息生成模块的索引文件。它被称为 准备阶段， 因为它 准备 模块的索引文件。该模块的第二个 QDoc 运行还解析所有模块的源文件，然后生成模块的文档页面。这称为 生成阶段， 因为它生成模块的文档。

该模块的文档可能包含指向一个或多个其他 Qt 模块文档的 HTML 链接。例如，大多数 Qt5 模块包含 QtCore 中 文档的链接。当 Qt 模块包含其他 Qt 模块文档的链接时，该模块据说依赖于其他 Qt 模块。因此，当 QDoc 运行该模块的 生成阶段时 ，它还必须加载这些模块的索引文件，以便它可以创建这些模块。

因此，当 Qt 构建系统生成 Qt 文档时，它首先为每个模块运行一次 QDoc，以执行 准备阶段 以生成所有索引文件。然后它为每个模块运行 QDoc 一次以执行 生成阶段 ，其中它使用依赖索引文件生成模块的文档，包括它找到的任何跨模块链接。每次执行 QDoc（ 准备阶段 和 生成阶段 ）都会解析模块中包含的所有源文件，并且在 生成阶段 还会解析依赖模块的索引文件。QDoc 运行之间不保留或保留任何内容。

为什么单一执行模式更快

顾名思义，单一执行模式使用单个 QDoc 进程生成所有 Qt5 文档。单个 QDoc 进程仍然为每个模块执行 准备阶段 ，然后为每个模块执行 生成阶段 ，但存在一些差异。首先阅读主 qdocconf 文件。然后，它读取主列表中的每个 qdocconf 文件，并为每个模块执行 准备阶段 。在 准备阶段 ，解析模块的所有源文件以构建模块的语法树。然后生成模块的索引文件，尽管 QDoc 不会在 生成阶段 重新读取索引文件。这里的重要区别是在生成索引文件之后保留模块的语法树，因此在为所有模块运行 准备阶段 之后，QDoc 仍然具有它构建的所有语法树。

然后，QDoc 再次处理每个模块以进行 生成阶段 。但是现在 QDoc 不需要重新解析每个模块的源文件，因为模块的语法树仍在内存中。QDoc 也不需要重新读取依赖模块的索引文件，因为它仍然具有内存中这些模块的语法树。它仍然只是遍历每个模块的语法树以生成文档页面。

因此，QDoc 只解析一次源文件一次，不需要读取索引文件。这使得单一执行模式比标准模式快得多。预计 Qt 构建系统最终将在单一执行模式下运行 QDoc。但是，可能需要更改主 qdocconf 文件，因此上述用于在单一执行模式下运行 QDoc 的方法可能必须更改，请观察此空间以进行更新。

QDoc 如何工作

QDoc 首先读取您在命令行中指定的配置文件。它存储配置文件中的所有变量供以后使用。它使用的第一个变量之一是 outputformats 。该变量告诉 QDoc 它将运行哪些输出生成器。默认值为 HTML ，因此如果未 outputformats 在配置文件中设置，QDoc 将生成 HTML 输出。这通常是您想要的，但您也可以指定 DITAXML 来获取 DITA XML 输出。

接下来，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 应如何呈现文档中的文本和图像元素，或文档的大纲结构。

QDoc 手动 命令索引 ◦