Doxygen + Graphviz windows+Windows Help Workshop下安装配置（图解）

一．什么是Doxygen?

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。
Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。

因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

目前Doxygen可处理的程序语言包含：

· C/C++

· Java

· IDL (Corba, Microsoft及KDE-DCOP类型)   

而可产生出来的文档格式有：

· HTML

· XML

· LaTeX

· RTF

· Unix Man Page

而其中还可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透过一些工具产生出PS或是PDF文档。

 

二．安装Doxygen

· 1.1 安装 Doxygen 1.7.4(Windows) 

· 1.2 安装 graphviz 2.28.0(Windows)

graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。

· 1.3 安装 Windows Help Workshop 1.32

Doxygen 使用这个工具可以生成 CHM 格式的文档。

本文环境为Windows 7 x64

一直在使用javadoc，奈何c\c++，python等其他语言注释写的很好，但没有工具自动生成文档。

通过同事反应Doxygen可以针对各种语言生成文档内容。随即查阅了Doxygen的相关内容。

Doxygen介绍：

Doxygen 是一个 C++, C, Java, Objective-C、Python、IDL (CORBA 和 Microsoft flavors)、Fortran、VHDL、PHP、C#和D语言的文档生成器。可以运行在大多数类Unix系统，以及Mac OS X操作系统和Microsoft Windows 。 初始版本的Doxygen借鉴了一些老版本DOC++的代码；随后，Doxygen源代码由Dimitri van Heesch重写。

Doxygen是一个编写软件参考文档的工具。 该文档是直接写在代码中，因此比较容易保持更新。 Doxygen 可以交叉引用文档和代码，使文件的读者可以很容易地引用实际的代码。

详细请看http://www.oschina.net/p/doxygen

要想使用Doxygen，需要三大步骤

1.Doxygen及其相关内容下载

1.1Doxygen下载

      由于国内墙了Doxygen的官网，但sourceforge还是可以使用

http://sourceforge.net/projects/doxygen/?source=dlp 进行下载

本文使用的为Doxygen 1.8.3.1

安装，我们将在配置的时候使用doxywizard，Doxygen的GUI版本。

1.2HTML Help Workshop下载

如果你希望你的Doxygen自动生成chm，那么请下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll

http://www.microsoft.com/en-us/download/details.aspx?id=21138 进行下载

下载其中的htmlhelp.exe并安装，记住安装目录，我们将在Doxygen配置时使用。

1.3 Graphviz

Graphviz在Doxygen用于自动生成类图的工具。

登陆官网发现被墙了，只能在天朝大局域网内随便找个方便的连接了。

http://download.tech.qq.com/soft/53/54/85568/index.shtml，我们大腾讯肯定不会封

点击下载，请自动忽略旋风下载 =。=

安装并记录安装目录，同样我们一会需要配置Doxygen

2.配置Doxygen

2.1基本配置

在基本配置中，会介绍一些关于Doxygen的基本配置，例如各种乱码，输出内容等。

首先我们打开开始-》所有程序-》Doxygen-》doxywizard

在开始之前，打开Doxygen GUI frontend的File，保存到你需要做测试的目录

会出现一个Doxyfile的配置文件，修改选项后保存，下次通过Doxygen打开这个文件可以还原该项目的配置

第一步，选择你的工作目录（源代码位置），点击Select。

第二步，进行配置

首先修改Project name，选择扫描源代码的目录，Source code directory：，勾选Scan recursively

。

在Wizard的Topics下的Mode，选择All Entities，可以输出相对完整的功能，是否包含源代码看你自身情况，在下面选择好你的语言。这里作者使用的是C所以选择C or PHP

在Output中，如果你需要输出chm格式，请勾选。

在Diagrams中选择使用GraphViz包，来输出UML。

2.2字符集乱码

Expert中，你需要首选确定你所输出的语言，个人使用中文

在Expert的Input中，很重要的是INPUT_ENCODING项，如果你使用的为微软默认字符集请填写GBK，不然目录乱码。

在Expert的HTML中，首先要看HHC_LOCATION选项，添加安装目录（注：作者目录为D:/build/doxygen/hcc/HTML Help Workshop/hhc.exe）

勾选CHM_INDEX_ENCODING，在你源代码中的字符集是什么就填写什么，作者的C由于使用keil，所以填写为GBK，java对eclipse切换了字符集所以为UTF-8，还有注意给chm命名以方便寻找。

2.3GraphViz的输出

之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK

为了减少chm体积，在DOT_IMAGE_FORMAT中选择gif或者jpg，均可。

最后在DOT_PATH下面填入dot.exe的路径。

配置GraphViz 暂缺

2.4生成文档

之后点击Run-》Run doxygen。

这时你可以看到一个没有任何注释与说明的关系图。（chm请在html文件内寻找）

3.关于注释格式

由于Doxygen支持 javadoc的格式，但还有部分区别，按照如下方式可以作为注释的模板，可以参考Doxygen的具体文档，形成你自己的风格。

/**
* @brief 说明内容
* @param void
* @return void
* @author 123
* @version v1.0.0.0
* @date 2013
* @since Keil uVision4
* @bug
* @warning
*/

结尾：

      注意保存Doxygen的配置文件，下次使用打开该配置即可，Doxygen虽然说明了如何使用，但是作者开始并没进行保存，很多调整的配置项丢失。

具体配置图文说明如下：(主要参考1,2)

1. http://my.oschina.net/hava/blog/110874?fromerr=ZUKVi69r

2. http://blog.sina.com.cn/s/blog_a459dcf50102v7ft.html

3. http://blog.csdn.net/fly542/article/details/7164633

谢谢楼主的这篇文章，很容易就上手生成了html文档。只是在其中遇到一点问题，我如果完全按照楼主的设置来运行脚本，生成的html文档中的图片是无显示的,查看Log发现Doxygen运行的时候提示了一句:"warning: the dot tool could not be found at C:\Program Files (x86)\Graphviz2.38"，经过反复试验，将DOT PATH路径修改为:"C:\Program Files (x86)\Graphviz2.38\bin"则在生成的html文档中可以正常看到函数调用关系图片了。另外，楼主后面的生成chm文档的步骤为何没有呢。。。同样需要。毕竟html不方便传输携带。。。;)