(懒得调整结构与样式了,感兴趣可以直接看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对此提供了内置的支持,如果你试过,你会发现加与不加感叹号,注释所显示的颜色是有所不同的。
位置
* 规则一: o 简单地说,就是我们需要在每一个需要生成文档的类和函数等定义的前面放置一个 /*!...*/ 注释块。
由于类的定义都在头文件.h 内,如果按照规则一,我们我们在头文件的类定义前面放置注释块。但这样一来,别人看头文件的话,就会感到比较乱。所以,在前面的例子中,所有的注释块,都放到了相应的 .cpp文件内。怎么放呢?看前面的例子:
/*!
\fn void Widget::signal2(const QString&)
This signal is emitted when
*/
/*!
Creates a Widget Window.
*/
Widget::Widget(QWidget *parent)
: QWidget(parent)
{
}
我们都是学Qt的,肯定知道"信号"只不过是一个普通的函数而已,所以我们处理起来和其他函数是完全一样的。只是我们用了命令 \fn后跟函数的原型。
这就是下面要说的,
* 规则二: o 如果注释块和定义的类、函数等分离,那么我们需要使用特殊的命令来标记该注释块。
\class 类
\enum 枚举
\fn 函数
\macro 宏
\namespace 命名空间
\property Qt属性
\variable 变量
main.cpp注释先解释一下我们前面的注释生成的html文件:
* qdoc3工作时,会为我们的每个类生成两个html页面,分别为"类名.html"和"类名-members.html"。这两个对应我们非常非常熟悉的"QString Class Reference"及 "List of All Members for QString"这两个页面。(如果你没运行前面的例子,不妨看看手册中的这两页来找找感觉)
这样一来,是不是有些问题出来了:
* 这些页面如何管理呢?
* 这些类如何联系起来呢?
* 用哪个类做首页呢?
如何解决这个问题。
* 1. 建立一个页面作为起始页。(这是我们例子中做的, index.html)
* 2. 起始页中创建到生成的类的页面的链接。(例子中有 \l Widget)
* 3. 每个页面的头部创建导航条。(暂时没涉及)
/*!
\page index.html
\title First Exmaple
\section1 Description
This is a demo program.
\section1 Class
\list
\o \l Widget
\o second
\o third
\endlist
*/
如果你熟悉html语言,理解这段注释应该没有任何困难^_^
控制文档结构的命令:
part
|
chapter
|
section1
|
section2
|
section3
|
section4
做点改进
* 有没有觉得 这个注释块放到 main.cpp 有点不爽?因为它们main函数没任何关系
o 其实,我们可以新建一个 xxx.qdoc 文件,然后将main.cpp 拷贝到xxx.qdoc中
o qdoc3 工作时,不止扫描源代码,还扫描 .qdoc 文件。
一不小心又过了12点了,要睡了,看来下一篇又有得写了。
[ 此帖被dbzhang800在2010-09-23 12:20重新编辑 ]