Qdoc是开发者用于在软件工程中生成文档的一个工具。

它根据qdocconf文件的指示， 从工程的源文件中提取qdoc类型注释，并以html页面或者DITA XML2文档的形式格式化到文件中。

Qdoc在.cpp和.qdoc文件中查找注释，而不会在.h文件中查找。一条qdoc注释往往以一个前置声明符号（!）开始

Qdoc把以.qdocconf结尾的参数理解为QDoc configure file，configure file是使用者用以告诉qdoc何处存放源代码文件、头文件以及.qdoc文件，同时它也指定了以何种格式（HTML、DITA XML…）输出结果，以及输出文件的位置， 以及其它信息。

qdoc的目的文件是qhp文件，得到qhp文件后， 使用以下命令对qhp文件打包

然后就可以把它上传到 assistant程序， 或者使用QtHelp打开。

这种方法适用于构建不依赖其他项目(有依赖项的处理方式见下文)的单独项目, 当用户写好注释相关文件时， 以以下方式编写 qdocconf文件。

在qdocconf中写入最小信息集

使用qdoc命令输出文档，

一些额外的重要信息

描述工程基本信息：

qhp文件的描述信息：

qdoc生成文档有两种方式： standard mode 和 single mode。single mode是比较新的技术，它的准确度和速度都远远大于standard mode。 当然，一般的工程因为文档数量不多，其实两者直观上差别不大。

目前，Qt5 building system并没有使用single mode生成qdoc文档，而是使用了standard mode。当下在转换Qt4文档以识别Qt5模块化这方面，Standard mode是最简单的方法了。在Qt4中，QDoc运行一次，遍历所有的Qt4源代码文件，生成html格式的qdoc文档。在生成qdoc文档的同时，qt4 QDoc还生成了一个索引文件（index file）。这个文件用于在生成依赖于Qt的其它类库、软件产品的html文档时，序列化QDoc的操作，还可以用于把其它类库、软件产品的qdoc文档链接到qt4文档中。

在Qt5中，Qt被模块化，之后，越来越多的模块被加入到Qt5中，在5.5.时，已经有40多个独立模块了。这些模块都有着自己的文档，而不同模块的文档又存在着相互的链接和依赖。

Standard mode中，QDoc为每个模块运行了两次。第一次QDoc在某个指定的模块中运行，遍历所有的源代码文件，并根据获得的一些信息生成索引文件。这个阶段被称为“准备阶段”（prepare phase），因为它生成了索引文件，为下一步的进行做准备。第二次运行依旧遍历所有源代码文件，然后生成qdoc文档，这个阶段被称作“生成阶段”（generate mode），因为它生成了该模块的qdoc文档。

某个模块的qdoc文档可能会包含一个或者多个其它模块的html链接，例如，大部分模块的qdoc文档都有指向QtCore的链接。当一个qdoc文档包含指向其它模块的链接时，认为这个模块依赖于后者。因此当QDoc在该模块下执行生成阶段时，它必须加载所依赖模块的索引文件，以创建这些链接。

由此可知，当Qt5 Building System在生成Qt文档时，它先在每个模块中运行一次QDoc生成索引文件（准备阶段），然后又在每个模块中运行一次QDoc生成qdoc文档（生成阶段）；在第二个阶段，QDoc使用那些相互依赖（链接）的索引文件生成qdoc文档，并把相互之间的链接包含进去。每一次执行QDoc，都会遍历一次源代码文件，在生成阶段还会为依赖关系遍历索引文件。两次QDoc的执行期间没有缓存信息。

顾名思义，single mode执行一次QDoc就能生成所有的qdoc文档。其实这个QDoc过程仍然会在每个模块中执行一个“准备阶段”(prepare phase)，一个“生成阶段”(generate phase)，但是有所不同。它从读取master qdocconf文件开始，然后读取master qdocconf里面的qdocconf文件列表，并为每个文件所在的模块执行“准备阶段”，QDoc会遍历这个模块的所有源代码文件，以生成一个语法树，然后是这个模块的索引文件——尽管这个索引文件不会在第二个阶段中被读取。这里和standard mode不同的是，QDoc会在生成索引文件以后保留语法树；所以当所有模块的准备阶段结束后，QDoc仍保留着它建立的语法树。

接着QDoc执行生成阶段，但是这里QDoc已经不用再遍历模块下的所有源代码文件，也不用再读取索引文件，因为内存中保留着该模块的语法树。

这样，QDoc仅遍历一次源代码文件，并且不用读取索引文件，这也是single mode比standard mode快得多的原因。当前的趋势是Qt Building System中会最终使用single mode。

QDoc从读取由命令行传入的qdocconf文件开始，它把从该文件中读取到的变量保存起来，并在以后使用。例如它使用的一个较早传入的变量 outputformats，它告诉QDoc使用哪个输出生成器。默认是HTML，所以如果你不设置outputformats，QDoc会生成html文档。这通常能够满足用户的要求，但是有时候，用户会需要DITA XML类型的输出，这时需要赋值 DITAXML。

然后QDoc读取headers或者headerdirs变量，并遍历工程里的所有头文件。QDoc不会读取头文件里的注释，而是使用头文件生成一个 master tree，它包含了所有应该在文档中被包括的节点。

接下来，QDoc读取sourcedirs和sources目录，遍历所有的cpp文件和qdoc文件，并读取文件里的qdoc注释。注意qdoc注释是以!开头的（在注释内部）

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

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

对于standard模式，文档的生成分为两个步骤： prepare 和 generate。

也可以使用一个命令完成， 但在本质上， 还是两个步骤：

对于single-exec模式，文档的生成一步完成。 但是在之前， 你需要建立一个master.qdocconf文件，并且在里面把所有的qdocconf文件的绝对路径列出来：

注意多了一个 -single-exec 选项