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 生成 HTMLQObject 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 应如何渲染文档中的文本和图像元素,或文档的大纲结构。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.