1. Qdoc 介绍

Qdoc是开发者用于在软件工程中生成文档的一个工具。它从工程的源文件中提取qdoc类型注释,并以html页面或者DITA XML文档的形式格式化到文件中。Qdoc在.cpp和.qdoc文件中查找注释,而不会在.h文件中查找。一条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类型定义。

本节说明了怎么使用qdoc命令读取源代码文件中的qdoc注释并生成文档,以及怎么生成 QDoc configure file(qdocconf文件)——当在命令行下使用qdoc工具时, 需要把qdocconf文件传给QDoc。

运行 QDoc

QDoc的可执行文档名为qdoc,如果要在命令行下运行,需要传入.qdocconf文件。

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

Qdoc把以.qdocconf结尾的参数理解为QDoc configure file,configure file是使用者用以告诉qdoc何处存放源代码文件、头文件以及.qdoc文件,同时它也指定了以何种格式(HTML、DITA XML....)输出结果,以及输出文件的位置。Configure file也包含了一些其它信息,详见下文。

运行 QDoc

QDoc的可执行文档名为qdoc,如果要在命令行下运行,需要传入.qdocconf文件。

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

Qdoc把以.qdocconf结尾的参数理解为QDoc configure file,configure file是使用者用以告诉qdoc何处存放源代码文件、头文件以及.qdoc文件,同时它也指定了以何种格式(HTML、DITA XML....)输出结果,以及输出文件的位置。Configure file也包含了一些其它信息,详见下文。

使用single mode运行qdoc

从Qt5.5开始,一个使用QDoc的新的方法产生了,它可以节省生成Qt5文档所需要的时间多达90%,这个新的方法就是single mode。目前在Qt5 编译系统(qmake)中仍在使用standard mode,single mode还不可用。只有在单独使用QDoc时才能使用single mode,而这往往出现在当你想为你自己的模块制作文档并且把它和其它模块集成起来的时候。

使用QDoc的single mode时,需要添加-single-exec参数,并传入一个master qdocconf文件,这个文件只是简单包括了所有Qt5模块的qdocconf文件路径。例如:

/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec

传入的master.qdocconf文件,需要列举Qt5模块的所有qdocconf文件:

/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

为什么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比较快

顾名思义,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工作过程

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 简介的更多相关文章

  1. ASP.NET Core 1.1 简介

    ASP.NET Core 1.1 于2016年11月16日发布.这个版本包括许多伟大的新功能以及许多错误修复和一般的增强.这个版本包含了多个新的中间件组件.针对Windows的WebListener服 ...

  2. MVVM模式和在WPF中的实现(一)MVVM模式简介

    MVVM模式解析和在WPF中的实现(一) MVVM模式简介 系列目录: MVVM模式解析和在WPF中的实现(一)MVVM模式简介 MVVM模式解析和在WPF中的实现(二)数据绑定 MVVM模式解析和在 ...

  3. Cassandra简介

    在前面的一篇文章<图形数据库Neo4J简介>中,我们介绍了一种非常流行的图形数据库Neo4J的使用方法.而在本文中,我们将对另外一种类型的NoSQL数据库——Cassandra进行简单地介 ...

  4. REST简介

    一说到REST,我想大家的第一反应就是“啊,就是那种前后台通信方式.”但是在要求详细讲述它所提出的各个约束,以及如何开始搭建REST服务时,却很少有人能够清晰地说出它到底是什么,需要遵守什么样的准则. ...

  5. Microservice架构模式简介

    在2014年,Sam Newman,Martin Fowler在ThoughtWorks的一位同事,出版了一本新书<Building Microservices>.该书描述了如何按照Mic ...

  6. const,static,extern 简介

    const,static,extern 简介 一.const与宏的区别: const简介:之前常用的字符串常量,一般是抽成宏,但是苹果不推荐我们抽成宏,推荐我们使用const常量. 执行时刻:宏是预编 ...

  7. HTTPS简介

    一.简单总结 1.HTTPS概念总结 HTTPS 就是对HTTP进行了TLS或SSL加密. 应用层的HTTP协议通过传输层的TCP协议来传输,HTTPS 在 HTTP和 TCP中间加了一层TLS/SS ...

  8. 【Machine Learning】机器学习及其基础概念简介

    机器学习及其基础概念简介 作者:白宁超 2016年12月23日21:24:51 摘要:随着机器学习和深度学习的热潮,各种图书层出不穷.然而多数是基础理论知识介绍,缺乏实现的深入理解.本系列文章是作者结 ...

  9. Cesium简介以及离线部署运行

    Cesium简介 cesium是国外一个基于JavaScript编写的使用WebGL的地图引擎,一款开源3DGIS的js库.cesium支持3D,2D,2.5D形式的地图展示,可以自行绘制图形,高亮区 ...

随机推荐

  1. Twitter Bootstrap JavaScript插件

    Twitter Bootstrap JavaScript插件本文收集了10款非常不错的JavaScript Twitter bootstrap扩展插件,利用Boostrap开发者可以节省大量的时间修复 ...

  2. JavaScript中的execCommand()命令详解及实例展示

    execCommand方法是执行一个对当前文档,当前选择或者给出范围的命令.处理Html数据时常用如下格式:document.execCommand(sCommand[,交互方式, 动态参数]) ,其 ...

  3. webapp 开发调试测试方法总结

    好久都没有发表过日志了,反正近期项目也已经接近尾声了,那么是时候该总结一下在项目中用到的技术了,请看:这里先废话几句,我们现在的开发模式是这样子的:先把本地的网页上传到远程服务器(因为好多设备都要去访 ...

  4. iOS基础 - 控件属性

    一.控件的属性 1.CGRect frame 1> 表示控件的位置和尺寸(以父控件的左上角为坐标原点(0, 0)) 2> 修改这个属性,可以调整控件的位置和尺寸 2.CGPoint cen ...

  5. 6 MySQL视图

    目录: 1. 视图概述 1.1 为什么引入视图 1.2 什么是视图 1.3 视图的好处 1.4 视图的分类 2. 视图的建立和删除 3. 实验 1. 视图概述 1.1 为什么引入视图[1] 问题:假如 ...

  6. go语言 strconv.ParseInt 的例子

    golang strconv.ParseInt 是将字符串转换为数字的函数,功能灰常之强大,看的我口水直流. func ParseInt(s string, base int, bitSize int ...

  7. 实现Launcher编辑模式(1) 壁纸更换

    Android Launcher分析和修改13——实现Launcher编辑模式(1) 壁纸更换 Posted on 2013-09-11 23:25 泡泡糖 阅读(212) 评论(3) 编辑 收藏 已 ...

  8. IceMx.Mvc 我的js MVC 框架 一、html代码的分离(视图)

    介绍 本人菜鸟,一些自己的浅薄见解,望各位大神指正. 本框架有以下优点 1.简单(调用简单.实现简单.不过度设计) 2.视图.控制器.模型分离(分离对于维护十分有必要) 3.组件化(每一个mvc模块儿 ...

  9. WP8开发札记(一)WP8应用生命周期管理

    在介绍生命周期前,我们先了解两个相关的概念. 1.墓碑机制:WP8与Android采用的真后台机制不同,WP8采用的是墓碑机制.一旦从当前应用程序离开(非退出),该应用会被墓碑化,这样可以更好的管理( ...

  10. VS2012下使用Moq进行单元测试

    单元测试虽然是个很老的东西了,但平时写代码一般都不写测试,因为VS调试完全可以满足了,所以一直也就没有用过,刚好在<Pro.ASP.NET.MVC.3.Framework>中看到了Moq这 ...