标题:Qt文档系统分析(一)更新到(五)
作者:dbzhang800
日期:2010-09-07 23:53
内容:
写在前面
只要打开Qt Assistant或Qt Creator的Help，或是打开在线版的 http://doc.qt.nokia.com ,Qt的漂亮的文档就会呈现在我们眼前。
而且 Qt的文档，长期以来似乎都是Qt的一大优势。比如大家在比较Qt和Wx，或比较Qt和GTK+时，Qt的文档似乎总是更胜一筹。
那么，这些文档时怎么生成的呢？
幕后英雄们
当然，这些文档幕后的应用是Qt的开发人员。我们对他们表示感谢。
但我们这儿关注的英雄呢？是生成这些文档的软件：
qdoc3qhelpgeneratorqcollectiongenerator先简单介绍一下它们的作用：(个人理解，不当请指正)
qdoc3 工作时需要一个配置文件 xxx.qdocconf (Qt Document Configure)根据该文件的设置，将源码代码中的各种符合规则的注释提取出来，生成一系列的 .html 文件如果只用来在线显示，这一步就足够了qhelpgenerator 工作时需要一个配置文件 xxx.qhp(Qt Help Project)根据该文件设置，将一系列的 html 文件变成 .qch 文件如果只是要求生成的用文件能通过 assistant 查看，到这一步也足够了qcollectiongenerator 工作时需要一个配置文件 xxx.qhcp(Qt Help Collection Project)该文件可以管理一系列的 .qch 文件。比如我们装完Qt后就有: qt.qch , assistant.qch, qmake.qch 等该文件可以对 assistant 显示的外观进行定制考虑到这些东西内容太多了，主要关注下qdoc3吧
一个小例子
先看一个例子，我们先编写一个很小很小的Qt程序，
先看first.pro文件，其实没什么看的，是吧
TARGET = first
SOURCES += main.cpp widget.cpp
HEADERS += widget.h
看一下我们的Widget类(其实是一个空类),下面是头文件 widget.h
#ifndef WIDGET_H
#define WIDGET_H
#include
class Widget : public QWidget
{
Q_OBJECT
public:
Widget(QWidget *parent = 0);
~Widget();
public slots:
void setValue(double v);
signals:
void signal1();
void..
#1 [yleesun 09-08 09:02]
关于如何写first.qdocconf 处说的不够详细！
#2 Re:Qt文档系统分析(二) [dbzhang800 09-10 08:39]
（懒得调整结构与样式了，感兴趣可以直接看blog中的版本：http://hi.baidu.com/cyclone/blog/item/ad615aaf2a3475f5fbed50c8.html）
为了尽快看到qdoc3生成的文档，在Qt文档系统分析(一)中，我们举了一个小小的可运行、可生成文档的例子。因为篇幅和时间有限，上文中未给出任何解释。本文的任务呢，就是把上个例子尽我所能地解释一下
qdocconf文件
前面我们提到了，qdoc3 工作时需要一个 xxx.qdocconf 文件：
project = First
description = First QDoc Exmaple
outputdir = html
headerdirs = .
sourcedirs = .
格式上，它和qmake的配置文件 .pro 是一致的：都是 "变量名 = 值" 这种格式
* outputdir
o 控制生成的 html 文档输出到哪个目录(本例中，输出到 ./html 目录下)
* headerdirs 和 sourcedirs
o 设置我们的 .h 和 .cpp 文件分别在哪个目录
o 为什么要设置这个呢？因为它要从我们的代码中提取信息啊^_^
* project 和 description
o 其实这两个和生成我们需要的文档没有必要的联系(所以你可以不要它们)
o 如果你运行过前面的例子，你会发现会生成html目录下生成了一个 first.index 文件
o index文件的作用，我们暂且不涉及。
代码注释
通过对前面的配置文件了解，我们知道，qdoc3之所以能生成这么漂亮的文档，依赖就是我们在代码中添加的注释。那么注释怎么写才好呢？注释放要放在什么位置呢？
格式
/*!
...
*/
* 注意到没，这是采用的C风格的注释，只不过要再加个感叹号。以备qdoc3来进行处理。
* qtcreator对此提供了内置的支持，如果你试过，你会发现加与不加感叹号，注释所显示的颜色是有所不同的。
位置
* 规则一：
..
#3 Qt文档系统分析(三) [dbzhang800 09-23 14:37]
http://hi.baidu.com/cyclone/blog/item/fa0185350681671f90ef39aa.html
在 Qt文档系统分析(一) 我们举了使用一个qdoc3的小例子，在 Qt文档系统分析(二) 我们对这个例子进行了简单的分析。但有些内容尽管我们提到了，但没做介绍：
* xxx.index 文件是做什么用的?
* 如何为所有的html文件添加统一的头和尾?
这是两个比较重要的东西，本文就主要介绍它们了。
重新贴出前面用的 xxx.qdocconf 文件(不影响理解的前提下此处加了一个url)：
project = First
description = First QDoc Exmaple
url = http://www.firstqdocexample.com/0.1.0
outputdir = html
headerdirs = .
sourcedirs = .
xxx.index
文件生成
前面提到 project、description及url是为了生成的 xxx.index 的服务的，而这个index我们自己是用不到的。那么它有什么用呢？
* project 指定了 xxx.index 文件的名字（即生成 first.index）
* description 和 url 我们可以通过打开该 first.index 文件来观察
...
看到了没？它们是INDEX节点的两个属性。
文件作用
接下来呢，我们通过qt.index文件来解释xxx.index文件的作用。qt.index坐落于Qt安装目录下的doc/html中，你可以随时查看验证。
...
文件中的主要内容就Qt中所有类以及信号、槽、属性等的索引。
为了说明它的作用，我们修改[]中所用的例子，添加一行{{{indexes = $QTDIR/doc/html/qt.index}}}(即我们使用qt.index):
project = First
description = First QDoc Exmaple
url = http://www.firstqdocexample.com/0.1.0
outputdir = html
indexes = $QTDIR/doc/html/qt.index
headerdirs = .
sourcedirs = .
outputencoding = UTF-8
执行
qdoc3 first.qdocconf[/qu ..
#4 [wd007 09-24 21:08]
这个不错的说。
#5 Qt文档系统分析(四-五) [dbzhang800 10-01 09:57]
文档分析四：http://hi.baidu.com/cyclone/blog/item/41651d955cb7a4067af4805a.html
和前三篇是一个具体小例子不同，本文主要看一下doxygen及qdoc3的配置文件。
Doxygen与qdoc
* 渊源
o Doxygen 本身是采用Qt编写的
o Doxygen 编写的初衷是作者为了给自己的软件生成类似Qt文档的文档（因为1997，Qt的qdoc源码和使用手册都是私有的）
* 兼容性
o qdoc3 自身都与先前版本不兼容
o Doxygen 可能与qdoc的早期版本比较兼容。但与qdoc3差别挺大了
* 便利性
o qdoc3 可以为 Doxygen 生成其需要的 tags 文件
o 同qdoc3一样，Doxygen 内置支持 Qt4.4 以后的帮助系统(xxx.qhp,xxx.qch等)
两个表格不好贴，不贴了...
文档分析五 http://hi.baidu.com/cyclone/blog/item/7c20fbf22692381db07ec591.html
源码中注释格式
考虑一下：qdoc3 是从哪些文件提取信息来生成 Qt Manual 的呢？
* $QTDIR/src 目录下的 *.cpp 文件
* $QTDIR/doc/src 目录下的 *.qdoc 文件
* $QTDIR/example 目录下的 *.cpp 文件
只要我们打开前两处的文件，就能见到如下的注释块：
/*!
*/
注释块中有大量以反斜杠"\"开始的命令，这些命令控制着最终生成的文档的结构。
而打开example中的文件，则能看到类似下面的内容
//! [0]
//! [0]
这种格式我们暂且不考虑(有命令可以提取两个[0]包住的代码，写入生成到 example 中的文档中)。