http://hi.baidu.com/cyclone/blog/item/a8b5277f247d3f0628388aa0.html
只要打开Qt Assistant或Qt Creator的Help,或是打开在线版的 http://doc.qt.nokia.com ,Qt的漂亮的文档就会呈现在我们眼前。
而且 Qt的文档,长期以来似乎都是Qt的一大优势。比如大家在比较Qt和Wx,或比较Qt和GTK+时,Qt的文档似乎总是更胜一筹。
那么,这些文档时怎么生成的呢?
幕后英雄们
当然,这些文档幕后的应用是Qt的开发人员。我们对他们表示感谢。
但我们这儿关注的英雄呢?是生成这些文档的软件:
- qdoc3
- qhelpgenerator
- qcollectiongenerator
先简单介绍一下它们的作用:(个人理解,不当请指正)
- 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 <QtGui / QWidget>
class Widget : public QWidget
{
Q_OBJECT
public :
Widget (QWidget *parent = 0 );
~Widget ();
public slots:
void setValue (double v );
signals:
void signal1 ();
void signal2 (const QString &);
};
# endif // WIDGET_H
这是类的实现 widget.cpp
# include "widget.h"
/*!
/class Widget
/brief The Empty Widget Class provides nothings.
The Empty Widget is a widget that
/sa QWidget
*/
/*!
/fn void Widget::signal1()
This signal is emitted when .
*/
/*!
/fn void Widget::signal2(const QString&)
This signal is emitted when
*/
/*!
Creates a Widget Window.
*/
Widget ::Widget (QWidget *parent )
: QWidget (parent )
{
}
/*!
Destroys this Widget.
*/
Widget ::~Widget ()
{
}
/*!
Set a new value /a v.
*/
void Widget ::setValue (double v )
{
}
再看一下 main.cpp 文件
/*!
/page index.html
/title First Exmaple
/section1 Description
This is a demo program.
/section1 Class
/list
/o /l Widget
/o second
/o third
/endlist
*/
# include <QtGui / QApplication>
# include "widget.h"
int main (int argc , char *argv [])
{
QApplication a (argc , argv );
Widget w ;
w .show ();
return a .exec ();
}
万事具备,还欠什么呢?注意我们前面提到 qdoc3 需要什么来着?
对了,再创建一个 first.qdocconf 文件就好了
project = First
description = First QDoc Exmaple
outputdir = html
headerdirs = .
sourcedirs = .
一切准备妥当了,运行一下试试吧
qdoc3 first.qdocconf
怎么样,看到效果了吧?什么?不如Qt自带的手册好看,当然网页头、网页尾、css什么我们都没设置。