文档生产工具 Doxygen

Doxygen是一种开源跨平台的，类似JavaDoc风格描述的文档系统，支持C、C++、Java、Objective-C等语言。可以从一套归档源文件开始，生成HTML，XML，pdf等不同风格的格式。

按照约定的格式注释源代码，用工具处理注释过的源代码产生文档，通过这种方式产生文档，有以下几个好处。

1. 便于代码和文档保持同步

2. 可以对文档做版本管理

 

 

使用方法

要使用Doxygen生成文档，主要有两件事

1. 一般用Doxywizard生成Doxyfile后，再手工修改或者通过向导进行修改。建议，一个项目使用单独的Doxyfile配置文件。

2. 按照Doxygen的约定，将代码文档化

3. 执行 doxygen Doxyfile

 

 

Doxygen统一采用UTF-8作为输出文件的编码格式。但微软的CHM编译工具(hhc.exe)不支持UTF-8，它支持GB2132

Doxygen的最新版本，可以从Doxygen的网站下载，我使用的是doxygen-1.8.7-setup.exe

Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形，例如类的继承关系图、合作图，头文件包含关系图等。可以从Graphviz的网站下载Graphviz的最新版本。Doxygen使用了Graphviz的布局引擎dot，所以在文档中将其称作dot。

 

 

 

Mode页面

Output页面：

Diagrams页面：

 

Expert页面：

我们关心这个页面下的HTML生成选项：

 

 

Input页面：

 

编码相关

Doxygen涉及的东西很多，编码设置很重要，如果设置不当，生成的文档会乱码，因此，需要认真对待。

所有的高级编码设置都在Expert标签下面：

 

 

 

配置文件的格式是unix下通常的文件格式，注释以#开头，tag = value1 [,value2 ].

所有配置，按照功能，分为两类。

一是控制输入选项，控制如何解释源代码，

二是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。

 

注释风格

头文件模板:
/** @brief 这里写你的摘要
*  @file 你的文件名
*  @author 谁tmd的搞的
*  @version 版本了
*  @date  你啥时候搞的
*  @note       注解. 例如: 本文件有什么具体功能啊,使用时要注意什么啊…..
*  @since    自从  例如: 自从2012年地球爆炸后这个文件就从地球上消失了…..
*/

 

函数的注释:
/**  这里写这个函数是干什么用的
@param[in]  输入参数1
@param[in]  输入参数2
@param[out]  输出参数1
@return    返回值解释一下
@warning 警告: 例如: 参数不能为空啊,内存要外部释放之类的费话
@note 注解 随便你了
@see                相当于是请参考xxoo函数之类的
*/

 

变量或者只有一行注解的东东,不超过一行的注释:
/**< 在这里写你要加的东西 */
OR
///< 在这里写你要加的东西

 

doxygen代码规范使用说明连接： http://blog.csdn.net/augusdi/article/details/6749845