Doxygen1.8.5+GraphViz2.34 构建源代码帮助文档

    原作网址：http://blog.csdn.net/fcqwin/article/details/16368253

    因为项目需要，试着将Qt工程的所有源代码生成了html格式的帮助文档。下面是简要的方法说明。

Graphviz

        （英文：Graph Visualization Software的缩写）是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。它也提供了供其它软件使用的函式庫。Graphviz是一个自由软件，其授权为Eclipse Public License。

Doxygen

        Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。

Doxygen配置

        运行Doxywizard，开始配置：

        单击Wizard选项卡，输入项目名，这个名字会作为文档的大标题，输入版本，也会出现在文档中，然后输入源代码的根目录，勾选”Scan recursively”，输入文档输出路径。在Working Directory中一般也输入源代码的根目录，主要是因为配置的一些选项中有的用相对路径，这个就可以作为相对路径的参照点。如图1所示：

        单击Diagrams标签，如果没安装GraphViz，则保持默认选择“Use built-in class diagram generator”。我这里已经安装了GraphViz2.34，将所有选项勾上。（注意这里仅是配置由GraphViz生产的东东，待会还要指定GraphViz的安装目录，否则Doxygen可不知道你的GraphViz在哪。。。。）

        单击Expert选项卡，会弹出一个有更多标签页的对话框：

        在"Project"标签页下，将OUTPUT_LANGUAGE设置为Chinese，因为我需要生成中文文档。勾选JAVADOC_AUTOBRIEF，即支持JavaDoc的语法，这样就可以用熟悉的JavaDoc风格的文档注释了。

        在" Input "标签页下，INPUT_ENCODING保持默认的utf-8，因为我的源代码文件的编码默认就是utf-8，你可以依据自己的指定相应的编码。FILE_PATTERNS下的后缀表明是需要扫描的代码文件，你可以只留下*.h、*.hpp、*.c、和*.cpp等，意思是只扫描C++头文件和源文件。下拉滚动条，会有EXCLUDE和EXCLUDE_PATTERNS表示不要进行解析的目录和文件，即工程目录下有的目录不需要进行文档化（比如.SVN配置目录），就用这两个排除掉。

        在"Source Browser"标签页下，勾选“SOURCE_BROUSER”，这样文档中就会附加一份源码，方便随时查阅。

        在"Dot"标签页下，DOT_PATH指定安装的GraphViz的bin目录所在位置，DOT_IMAGE_FORMAT可以指定GraphViz生成的图片格式，这里选择gif，如图所示：

        这个配置好的文件以后可以重复利用，每次点”Load…”装载进来，然后点击”Wizard…”，根据不同的工程，修改工程名字，版本，源代码根目录，文档输出目录就可以了，不用再重复上述配置。

源代码注释语法（JavaDoc）

        这里仅列出几条常用样例，详细语法请度娘之。。。

文件头注释

[java] view plaincopy

1. /** @file 
2.  * @brief  模型结构类. 
3.  * @author FCQ 
4.  * @date June6,2012 
5.  * @version 1.0.0.0 
6.  * @note 
7.  * 模型结构类的所有定义 
8.  */  

说明：    @file 独占一行，@file后我们空着，Doxygen会默认为是当前文件的文件名。

   @brief是有关该类的简要注释

   @note 后面另起一行是关于该文件的详细注释。（其本身独占一行）换行可用<br>。

 

类注释

[java] view plaincopy

1. /** 
2. * @class ClassBase class_base.h 
3. * @brief 所有类的基类 
4. * @author FCQ 
5. * @date June6,2012 
6. * @note 
7. * 基类的定义 <br>  
8. * 所有类均从me派生 <br>  
9. * 这里定义了所有基本操作 
10. */  

说明： @class 后面紧随当前类名和类所在的头文件名

             @brief是有关该类的简要注释

             @note后面另起一行是关于该类的详细注释。（其本身独占一行）换行可用<br>。

函数注释

[cpp] view plaincopy

1. //! ClassBase 的构造函数 <br>  
2. ClassBase(conststd::string&className,ClassBase *parent=0);  

说明： //! 一行注释开头，换行可用<br>。

             //!也可用来注释变量等，凡是只要其放在需要注释的（类、函数、变量、宏定义、枚举等）之前即可。

变量注释

[cpp] view plaincopy

1. int_id;                    ///< 每个实体的全局唯一ID  

说明： 一行代码的后面放置注释必须采用 ///<的格式，切不可采用//!，如果采用//!很肯能会导致Doxygen认为这是下一行的注释（因为它在下一行的紧邻前面）。

最终效果图