Qt文档系统分析（解释Qt文档的生成工具与过程）

写在前面

只要打开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什么我们都没设置。

图片:qdoc_first.jpg

http://www.qtcn.org/bbs/read-htm-tid-31757.html