首页 > 代码库 > 文档生产工具 Doxygen

文档生产工具 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。

 

 

image

 

Mode页面

image

Output页面:

image

Diagrams页面:

image

 

Expert页面:

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

  image

image

 

Input页面:

image

 

编码相关

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

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

image

image

 

 image

 

配置文件的格式是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