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格式),在浏览器查看,点击各个选项查看效果如下:

主界面:

查看某个函数的界面:


  • 2
    点赞
  • 4
    收藏
  • 打赏
    打赏
  • 2
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
©️2022 CSDN 皮肤主题:编程工作室 设计师:CSDN官方博客 返回首页
评论 2

打赏作者

小敏纸

你的鼓励将是我创作的最大动力

¥2 ¥4 ¥6 ¥10 ¥20
输入1-500的整数
余额支付 (余额:-- )
扫码支付
扫码支付:¥2
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值