我要评论下载doxygen的binary 包
为了使doxygen能够将类图、协作图等加入到文档中，还要下载安装graphviz for win。
graphviz 2.18下载：
http://www.graphviz.org/pub/graphviz/archive/graphviz-2.18.exe
全部安装后就可以开始使用了。
运行doxygen wizard.exe
如果你像我一样希望只通过图形界面运行doxygen的话，请在doxygen的bin目录中运行doxywizard.exe，这时按照doxygen根目录下的文档（doxygen_manual-1.5.2.chm）中 doxywizardusage一节的说明设置即可。主要包括，源码路径、工作路径、输出路径等。
点开始，即可生成文档
最后对文档生成过程中遇到的一些问题进行说明：
1、 中文问题：中文注释在文档中是乱码。
解决：在expert中的input选项页的input_encodeing中填入“gb2312”，这样基于gb的文本编辑器生成的代码就可以正常使用了。
但是，还有一个无法彻底解决的问题就是，当输出语言为中文时左边的导航栏的所有中文仍然是乱码。哪位有解决方案，请务必告知！
2 图形问题：无法绘制类图协作图等图形。
首先确保安装了graphviz forwin，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在expert的dot_path中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。
如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。
3 输出chm的问题：如何输出.chm文件
1. 你必须安装微软或其相兼容的chm编译系统。通常为html help workshop。
2. 首先在[wizard...]的output页面中，选择html，然后选择到prepare for compressed html(.chm)。
3. 其次在[expert...]的html页面中，将hhc_location指向微软的hhc工具。通常为c:/program files/html help workshop/hhc.exe。然后点击ok，保存，编译即可。
![clip_image004[1]](http://www.lhsxpumps.com/_images5/10qianwan/20200928/b_0_202009282349287899.jpg "clip_image004[1]")
hhc_location中输入hhc.exe文件的路径。hhc.exe可以通过安装html help workshop获得。
html help workshop 地址：
http://www.microsoft.com/downloads/details.aspx?familyid=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en
4 如何像msdn那样在左边的树中显示函数列表？
打开[expert...]的html页面，然后选中toc_expand即可。
5 如何去掉chm附带的chi文件？
注意在默认情况下，chm会有一个chi文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了chm，而没有上传chi文件，导致无法正常显示的情况。我不知道是否可以通过工具重建chi文件，但是我觉得关闭这个功能即可。打开[expert...]的html页面，取消generate_chi即可。
6 如何像msdn那样右边每页显示一个函数？
这个问题其实比较棘手，在[expert...]中的project页面，下面有一个选项叫做separate_member_pages，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编译一下doxygen，在memberlist.cpp的writedocumentationpage函数中将container->writequickmemberlinks(ol,md);连同附近几行屏蔽掉即可。
7 如何在chm中去掉当选择subgrouping后去掉分组的组信息？
这个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽writegroupindexitem函数的doxygen::indexlist.addcontentsitem，doxygen::indexlist.inccontentsdepth和doxygen::indexlist.deccontentsdepth();即可，具体不解释了，一看便知。
8 如何修改或者去掉右下脚generated at ...的文字？
打开[expert...]的html页面，然后在html_footer中指定相应的html文件即可。注意html_footer中至少包含body和html结束标记。即一个最小的尾部html至少是这样</body></html>。同理，如果你要指定了html_header，他至少包含<html><head></head><body>
9 如何生成组？
组就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就被放置在同一个组中。
10 如何生成中文帮助？
点击[expert...]，在页project 的output_language，选择chinese，这样输出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。
11 如何彻底解决doxygen的输出中文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-textsearch全文搜索选项，他在进行全文搜索的时候，应该是打开文件然后按照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选择自己喜欢的就好。
如您对本文有疑问或者有任何想说的，请点击进行留言回复，万千网友为您解惑！
网友评论