Qt文档系统分析(一)

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