• 做一个幸福的人,读书,旅行,努力工作,关心身体和心情。
  • 不管有没有人爱,也要努力做一个可爱的人。不埋怨谁,不嘲笑谁,也不羡慕谁,阳光下灿烂,风雨中奔跑,做自己的梦,走自己的路。

Doxygen简单使用

产品 lcq 4年前 (2015-04-19) 705次浏览 0个评论

最近在看TWD项目源码的时候,整个代码结构看起来有点头疼。这促使我又想起了以前用过的Doxygen这个代码注释生成利器。而且我觉得反正代码是要写注释的,那为什么不按照一定的规则来写注释,让Doxygen给我们生成一个注释文档呢。Doxygen生成的注释文档看代码结构还是很方便的。比如,可以看函数的调用关系,专注函数的注释等等。各种百度Google一晚上之后,终于初步搞定了Doxygen。好了,废话不多说了。记录一下Doxygen的简单使用过程。

首先,说说需要安装哪些软件。毫无疑问,Doxygen是要安装的。然后,如果你想要生成一个chm格式的注释文档,需要借助一个HTML Help Workshop的软件。最后,如果你想生成一个函数之间调用的关系,Graphviz必不可少。这三个软件如果你想用最新版,请自己Google百度下载之。如果你想用我写这篇文章的时候的版本(Doxygen:1.8.9.1,Graphviz:2.38,HTML Help Workshop没什么影响),我也提供了一个下载链接,下载解压之后,这三个软件都在等着你。

然后,装上这三个软件之后就是对Doxygen的一些基本配置。下面以图片的形式来展示一些配置。

运行Doxywizard会看到如下界面。

说明:设置目录就是Doxygen对项目的一个配置文件。输出目录就是输出的chm,HTML文档。

经过上面的步骤,基本可以生成一份漂亮的注释文档了。最后来一张,我用Doxygen生成的chm文档的一个截图:


最后,在生成注释文档的过程中,可能发生各种各样的乱码问题。比如生成的chm文档左边树目录乱码,文档乱码。下面是我从网上找的一些乱码的解决办法。一块粘贴过来,如果你遇到了,你先试着用下面的方法解决一下。

DoxyGen的实现中大概有三处编码的设置。首先是,doxyfile,也就是配置文件。其次,INPUT_ENCODING,也就是DoxyGen需要解析的输入文件的编码。最后,就是输出的编码。譬如CHM左边的索引编码。

首先是chm的标题乱码,这个比较好解决,因为DoxyWizard使用QT做的界面,它内部做了转换,所以在DoxyWizard中输入中文,在保存的时候,他自己做了转码,导致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件,输入相应中文即可。注意保存 的时候保存成ANSI编码即可。保存成其他格式的话可能需要去掉BOM,比较麻烦,没研究了。这个相应的编码设置在[Expert…]中,页 Project 的 DOXYFILE_ENCODING,不输入或者默认为UTF-8都行。

其次是右边内容乱码,这个多半是因为你没 有配置好输入的文件编码类型造成的。在[Expert…]的Input页面中,有一个INPUT_ENCODING,这个选项表示输入文件的编码方式,这要和你处理的源文件格式一致。对于我们来说(使用vs的人),一般设置为GB2312。当然,再次声明,编码方式取决于源文件的编码方式。如果文件 编码已经是UTF-8了,然而你还将其设置成GB2312,那么DoxyGen会将UTF-8当成ANSI再进行一次UTF-8转换,自然会出错了。

最后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。这个只需要将chm索引的编码类型修改为GB2312即可。在HTML的CHM_INDEX_ENCODING中输入GB2312即可。然而这种方法下,还有一个瑕疵之处,就是chm的搜索页的搜索结果中显示的中文 文字却变成乱码了。这是因为DoxyGen默认开启了HTML Help Workshop的Full-text search全文搜索选项,他在进行全文搜索的时候,应该是打开文件然后按照ANSI进行搜索的,(资料表示HHW不支持UTF-8,仅支持ISO- 8859-1或者windows-1252编码。)而Doxygen生成的右边界面统一是UTF-8,这自然出现了问题。而在这种情况下做全文搜索,理论 上只能搜索英文。

无奈,我们的解决方案只能是重新编译DoxyGen代码,为了满足搜索,只要保证右边的页面文件不是UTF-8即可。 我们首先修改writeDefaultHeaderFile这个函数的代码,将其charset=GB2312。然后在 TranslatorDecoder的构造函数中修改m_toUtf8 = (void*)-1;即屏蔽文本写入时最终的转换函数。最后删除INPUT_ENCODING的设置或者输入UTF-8。这样会使DoxyGen认为我们 的文本是UTF-8的,从而不用进行转换。生成替换原始的DoxyGen即可。

另外需要补充的是,还有一种方案是不用修改作者的源代码,但是需要将DoxyGen生成的右边的HTML文件使用工具(如iconv)手工转换成GB2312,然后再使用HTML Help Workshop生成,网上有篇文章介绍过,我测试一下,也是没有问题的。

最后,doxygen是一个开源项目,并且支持vs2005项目,这样一来,如果你觉得哪里不顺手,完全可以把代码下载后自行编译。虽然我感觉doxygen的代码写的不能算是perfect,但是对于一个这样的工程,我们无论如何都需要一种敬意。祝好运~

这样,基本上就能够用doxygen生成漂亮的文档了。代码方面,doxygen支持多种格式的注释风格,根据manual选择自己喜欢的就好。


参考资料:

1、doxygen相关问题

2、Doxygen初学与简单应用

3、Doxygen + Graphviz windows下安装配置(图解)

4、Doxygen 1.7.4 安装配置指南(windows)


另外,在百度文库上找到了一篇Doxygen方面的中文文档,应该是比较正式的官方的文档,被人翻译成的汉语,也一并提供链接下载:Doxygen中文手册.pdf


我自己遇到的问题,记录一下,以防以后再遇到束手无策。

1、生成的chm文档左边树目录乱码:我将Expert下的HTML项下的CHM_INDEX_ENCODING改成GB2312就好了。


乐趣公园 , 版权所有丨如未注明 , 均为原创丨本网站采用BY-NC-SA协议进行授权 , 转载请注明Doxygen简单使用
喜欢 (0)
发表我的评论
取消评论

表情 贴图 加粗 删除线 居中 斜体 签到

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址