Doxygen心得
技术 2008-10-08 16:24:54 阅读2524 评论0 字号：大中小 订阅
几年前，看过几个开源项目的文档，发现每个开源都会有一个帮助文件，感觉注释非常详细。当时就感慨开源项目的人精力充沛。后发觉注释和代码有很多相似之处，经过研究，了解到了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至少是这样