Doxygen学习和使用心得

<br /> 几年前，看过几个开源项目的文档，发现每个开源都会有一个帮助文件，感觉注释非常详细。当时就感慨开源项目的人精力充沛。后发觉注释和代码有很多相似之处，经过研究，了解到了doxygen。正巧前段时间公司要程序生成文档，以前很多都是都是手工完成的。经过交流，我们修改了部分源代码的注释，同时我写一个帮助，放到这里。<br /> doxygen是一款源代码帮助文档生成工具

hitxiaya

1910人浏览 · 2010-11-26 13:51:00

hitxiaya · 2010-11-26 13:51:00 发布

几年前，看过几个开源项目的文档，发现每个开源都会有一个帮助文件，感觉注释非常详细。当时就感慨开源项目的人精力充沛。后发觉注释和代码有很多相似之处，经过研究，了解到了doxygen。正巧前段时间公司要程序生成文档，以前很多都是都是手工完成的。经过交流，我们修改了部分源代码的注释，同时我写一个帮助，放到这里。
doxygen是一款源代码帮助文档生成工具。依靠源代码中的注释，doxygen可以轻松的生成多种格式的帮助文档，供开发者阅读。

doxygen的使用方法很简单：

第一步，需要修改源代码文件，规范现有注释。为了使注释轻松智能的变成可读的文档。doxygen规定了自己的注释格式，这样太才可以解析。最常用的注释格式是：

/**
there is comment.
*/

或
/*!
there is comment.
*/

同时，为了区分注释的用途，doxygen定义了很多关键字，用来标识注释描述的代码段或者用途。常用@后面跟用途关键字来标识，关键字在doxygen附带的帮助文件中有很详细的解析(在Special Commands这一节中)，这里就不在累赘了。这里有一个地方需要注意一下，描述的各个分段之间最好用tab空开，用空格有的时候会出现问题。
如：

/**
* @brief 这是一个函数
* @param a 参数一
* @param b 参数二
* @return 无返回值
*/
void fooFun(int a, int b);

第二步，建立doxygen配置文件。doxygen执行的时候需要一个配置文件，即每生成一个chm都会有一个配置文件来进行生成工程具体信息的描述。手工编写那个配置文件比较繁琐，还好doxygen随身附带了一个DoxyWizard，利用这个向导。你可以方便的配置想要的信息。注意DoxyWizard仅仅是一个界面，他最终编译的时候还是执行了doxygen.exe，传输时不要只拷贝这一个文件。

       打开DoxyWizard，会发现DoxyWizard分成了三个区域。
       在step1中有三个按钮。
             按钮[Wizard...]里面配置项目的一些基本信息
             按钮[Expert...]包含高级配置信息
             按钮[Load...]加载一个doxygen配置文件

在step1中，有个最重要的设置就是在[Wizard...]的Project页面中的Source code directory选项。把这个指向你的源代码文件路径。Scan recursively表示是否递归遍历。

       step1完成之后，你必须要保存一下doxygen配置文件。只需要点击step2的保存按钮即可。
       step3中的工作目录，也就是doxygen最终生成的帮助文档(chm)的存放路径。
       最后，点击step4中的[Start]按钮即可。

在Output列表中。是doxygen生成编译时生成的信息。注意上面已经提到过，DoxyWizard和doxygen是两个不同的进程，所以在DoxyWizard输出日志的时候可能会有停顿。具体显示时候的通信机制我没有看，但这和机器或者doxygen本身的代码没有关系。

--------------------------------------------------------------------------------

我在这里主要讲一些基本常用的属性，很多我觉得意义不大的，请自行研究，这里就不过多解释了。
在[Wizard...]中没有特别复杂的地方，稍微看一眼便知。

在[Expert...]按钮中，有一个tab页，下面来逐一解释：

         Project页面，主要包括项目的基本配置。
             TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议符合习惯，设置成4。
             OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。
             SUBGROUPING这个选项选择后，输出将会按类型分组。

         Build页面，这个页面是生成帮助信息中比较关键的配置页面
             EXTRACT_ALL 表示输出所有的函数，但是private和static函数不属于其管制。
             EXTRACT_PRIVATE 表示输出private函数。
             EXTRACT_STATIC 表示输出static函数。同时还有几个EXTRACT，相应查看文档即可。
             HIDE_UNDOC_MEMBERS 表示那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
             INTERNAL_DOCS 主要指是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都将在目标帮助中不可见。
             CASE_SENSE_NAMES 是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说，建议永远不要开启。
             HIDE_SCOPE_NAMES 域隐藏，建议永远不要开启。
             SHOW_INCLUDE_FILES 是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。
             INLINE_INFO 如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
             SORT_MEMBER_DOCS 如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。
             GENERATE_TODOLIST 是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。
             SHOW_USED_FILES 是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
             SHOW_FILES 是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

         Messages页面主要用来设置编译时的输出信息选项。编译时的输出信息，主要可以用来提醒一些输入的错误语法。
             QUIET 如果开启，那么表示关闭编译时的输出信息。
             WARN_FORMAT 表示日志输出的格式，没必要修改。
             WARN_LOGFILE 表示信息是否输出到LOG文件，因为有DoxyWizard的存在，所以这个选项没有必要使用。

         HTML页面
             CHM_FILE 表示输出的chm文件路径
             GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。
             TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。
             这个页面关系到生成chm的问题，不过很多选项很简单，一看便知。

Preprocessor 页面是预处理页面，里面也有一些配置，但是个人感觉使用默认就行了。其他的几个页面，基本上都要依赖于某些其他第三方的模块，尽管有些doxygen自带了，但是其详细说明，还得考读者自行研究。

--------------------------------------------------------------------------------

同时附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen自建命令，HTML命令方式和XML命令方式。所有的命令都是以'/'或者'@'字符开头，这表明如果你的注释中有'/'开头的单词，你必须要修改成'//'。

由于doxygen命令比较多，另外就是doxygen的帮助文档也是非常完善，所以，这里仅仅列举几个常用的命令，其他命令请自行参考帮助文件。

@addtogroup 添加到一个组。
@brief 概要信息
@deprecated 已废弃函数
@details 详细描述
@note 开始一个段落，用来描述一些注意事项
@par 开始一个段落，段落名称描述由你自己指定
@param 标记一个参数的意义
@code .. @endcode 包含一段代码
@fn 函数说明
@ingroup 加入到一个组
@return 描述返回意义
@retval 描述返回值意义
@include 包含文件

--------------------------------------------------------------------------------

问题：

如何编译成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，保存，编译即可。

如何像MSDN那样在左边的树中显示函数列表？
打开[Expert...]的HTML页面，然后选中TOC_EXPAND即可。

如何去掉CHM附带的CHI文件？
注意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，而没有上传CHI文件，导致无法正常显示的情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开[Expert...]的HTML页面，取消GENERATE_CHI即可。

如何像MSDN那样右边每页显示一个函数？
这个问题其实比较棘手，在[Expert...]中的Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编译一下doxygen，在memberlist.cpp的writeDocumentationPage函数中将container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可。

如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？

这个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽writeGroupIndexItem函数的Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知。

如何修改或者去掉右下脚Generated at ...的文字？
打开[Expert...]的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY和HTML结束标记。即一个最小的尾部HTML至少是这样</BODY></HTML>。同理，如果你要指定了HTML_HEADER，他至少包含<HTML><HEAD></HEAD><BODY>

如何生成组？
组就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就被放置在同一个组中。

如何生成中文帮助？

点击[Expert...]，在页Project 的OUTPUT_LANGUAGE，选择Chinese，这样输出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。

如何彻底解决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-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，但是对于一个这样的工程，我们无论如何都需要一种敬意。祝好运~

本文基于DoxyGen1.5.6及1.5.7。

关键词：DoxyGen 注释文档中文乱码解决方案