Doxygen自动文档生成工具在Eclipse中的集成及使用举例

你有为软件编写说明文档的苦恼吗？当别人甩给你一个庞大的系统，让你根据里面的代码注释理解后写出一份完整的开发文档，你会怎么办？一个个的看代码 然后耗时N天来写吗？这既是一份苦差事也极其耗时，有没有更好的办法呢？比如根据代码注释自动生成详尽的说明文档……可能有人会说用Javadoc就是 了，要是C/C++、Python、C#等语言写的软件呢？有没有类似Javadoc的东西？

Yes，当然有，Doxygen就是这样一个能满足你需求的工具。Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，可将程序中的特定批注转换成为说明文件，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。被Boost、OpenCasCade等诸多项目作为文档生成工具的不二选择。

由于我主要的开发语言是Java，所以在这里主要说明Doxygen在Eclipse里的集成及使用步骤。

 

1. 安装doxygen工具

在集成之前需要安装doxygen工具，下载方法有两种：目前最新版是1.8.6

（1）官方网站下载（建议）：Doxygen：Downloads

 （2）在sourceforge下载：Doxygen

2.安装doxygen在Eclipse中的插件：Eclox

建议在其官方网站下载：Eclox

 

下载eclox_0.8.0.zip后解压，安装插件的方法也有几种：

1. 将eclox_0.8.0中的plugins和features目录里的内容，移动到eclipse中的plugins和features目录里重启即可，最简单。

2. 通过links方法安装插件（建议该方法，具体可Google）。

2. 采用Eclipse里的update manager安装插件，具体方法请看这里。

注意：网上都说同时要下载eclox.update_0.8.0.zip并解压安装，其实完全没必要，eclox.update_0.8.0只是版本的更新过程，里面包含的都是最新版本和历史版本插件，而我们需要的只是最新版本的，故不需要下载此压缩文件。

如果这两个步骤都完成后，重启eclipse之后，就可以发现在工具栏上多了一个@的图标，如下图所示，表示安装成功。

3. 在Eclipse中配置doxygen运行环境

工具栏上 windows->preferences->Doxygen, 点击Add，添加doxygen安装目录中的bin目录，如下图所示：

 

到此doxygen在Eclipse中的集成工作就完成了。

 

4. 使用Doxygen生成文档过程举例

4.1 自动生成工程的doxygen文件

首先选择你要生成文档的工程，

然后File->New->others....,出现下面的选择框，选择Other中的Doxyfile。

点击next，配置Doxygen，定好文件的名字，点击Finish就OK了。

当然到此还没结束，最重要的一步还没完成，就是自动生成doxygen文件后需要我们自己配置各个参数和选项。

4.2 配置doxygen文件参数和选项

配置Doxygen文件参数也有三种方式：

4.2.1 使用Eclipse中集成的doxygen editor进行修改

在Eclipse中打开刚刚自动生成的doxygen文件，默认的配置如下：

比如在Eclipse中我用的配置选项如下：

建议大家如果不理解各个选项，可以尝试每个选项的生成效果，以找出自己最想要的文档格式。

4.2.2 使用Doxygen安装程序自带的GUI工具

找到Doxygen的安装目录下的bin目录里，如下图所示可以看到有个GUI工具：

打开后如下图所示：

与Eclipse中大同小异，各个参数选项慢慢琢磨吧，很简单。

4.2.3 直接用文本编辑器进行修改

针对doxyfile可直接用文本编辑器进行编辑，建议用Notepad++或写字板等打开，不要用无排版的记事本。

主要有以下内容需关注：

• <OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。
• <INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把<RECURSIVE> 标记设置为Yes。
• <FILE_PATTERNS>：在默认情况下，doxygen 会搜索具有典型 C/C++ 扩展名的文件，比如.c、.cc、.cpp、.h 和.hpp。如果<FILE_PATTERNS> 标记没有相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用.c86 作为C 文件扩展名，就应该在<FILE_PATTERNS> 标记中添加这个扩展名。
• <RECURSIVE>：如果源代码层次结构是嵌套的，而且需要为所有层次上的 C/C++ 文件生成文档，就把这个标记设置为Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为Yes，doxygen 就会递归地搜索整个层次结构并提取信息。
• <EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为Yes。
• <EXTRACT_PRIVATE>：把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。
• <EXTRACT_STATIC>：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。
• <OUTPUT_LANGUAGE>：默认 = English，文档语言（自动生成的文字部分），可以指定为Chinese。
• <DOXYFILE_ENCODING>：默认 = UTF-8，默认编码为UTF-8，这样可以支持中文。
• <PROJECT_NAME>：项目名称，多个单词需要使用引号(“”)。
• <PROJECT_NUMBER>：项目版本号。
  

4.3 运行doxygen文件生成最后的文档

配置完成后在Eclipse中点击@插件按钮选择doxygen配置文件即可生成文档了。

可以在控制台看到生成详细过程，如果有如何配置错误如指定的路径或文件不存在等，都会给出提示，按要求重新配置即可。

打开生成文档里的index.html（如果是html格式），在浏览器查看，点击各个选项查看效果如下：

主界面：

查看某个函数的界面：

更多 0