Qt文档系统分析(二)

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
  • 控制生成的 html 文档输出到哪个目录(本例中，输出到 ./html 目录下)
• headerdirs 和 sourcedirs
  • 设置我们的 .h 和 .cpp 文件分别在哪个目录

  • 为什么要设置这个呢？因为它要从我们的代码中提取信息啊^_^

• project 和 description
  • 其实这两个和生成我们需要的文档没有必要的联系(所以你可以不要它们)
  • 如果你运行过前面的例子，你会发现会生成html目录下生成了一个 first.index 文件
  • index文件的作用，我们暂且不涉及。

代码注释

通过对前面的配置文件了解，我们知道，qdoc3之所以能生成这么漂亮的文档，依赖就是我们在代码中添加的注释。那么注释怎么写才好呢？注释放要放在什么位置呢？

格式

/*!



...



*/

• 注意到没，这是采用的C风格的注释，只不过要再加个感叹号 。以备qdoc3来进行处理。

• qtcreator对此提供了内置的支持，如果你试过，你会发现加与不加感叹号，注释所显示的颜色是有所不同的。

位置

• 规则一：

  • 简单地说，就是我们需要在每一个需要生成文档的类 和函数 等定义的前面放置一个  /*!...*/   注释块。

由于类的定义都在头文件.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 后跟函数的原型。

这就是下面要说的，

• 规则二：
  • 如果注释块和定义的类、函数等分离，那么我们需要使用特殊的命令来标记该注释块。

/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函数没任何关系
  • 其实，我们可以新建一个 xxx.qdoc 文件，然后将main.cpp 拷贝到xxx.qdoc中
  • qdoc3 工作时，不止扫描源代码，还扫描 .qdoc 文件。

一不小心又过了12点了，要睡了，看来下一篇又有得写了。