偶看新闻大秦帝国纵横种子:Doxygen应用记录
来源：百度文库 编辑：偶看新闻 时间：2024/04/28 22:34:09
阅读程序是很费力的事，一边阅读一边做笔记是必须的。把笔记直接做在源程序里，然后用工具生成文档，则可以事半功倍。当然，如果是自己写的程序，那么按要求写好注释也是很好的习惯，以便生成文档。
从程序注释生成文档的工具应该有很多，针对C/C++程序来说，Doxygen的应用相当广泛。主要是这个工具在cygwin下有编译好的安装版，而且我正在看的计算程序也刚好在cygwin下可以很好的编译与运行，所以也没有选择过程直接就用了。下面，主要记录一些使用中的要点。以后在应用中遇到的问题再逐步补充。
一、操作过程
１）生成配置文件
运行命令doxygen -g可生成名为Doxyfile的配置文件。其实该文件的注释相当详细，搞清的各选项含义，按照自己的要求修改配置文件，使用起来就能得心应手了。
２）生成程序文档
运行命令doxygen Doxyfile，则按照配置文件的设置要求生成程序文档。就这么简单，真是让我感叹。
二、源程序的注释要求
既然程序文档是从注释中自动生成的，那么对注释自然要有一定的要求。doxygen手册中提供了好几种程序所支持的注释规则，但使用起来最好尽量用一致的注释。不过因为在C/C++程序中经常也出现两种不一样的注释，所以为了方便。在函数说明等需要大量注释文字的地方可使用与JAVADOC一样的方法。另要说明的是，注释是出现在代码之前，而不是之后。
/**
*简要说明
*
*注释文本
*/
而在行内的简单注释则使用三斜杠方式。///注释文本
对于C++程序的注释，要求先对类本身写注释文档，才能对类的成员写注释。
对于C程序的注释，要求先对文件本身写注释，才能对其中的函数进行注释。文件注释方法：在文件开头写
/**/file
*文件简要说明
*
*文件详细说明
*/
另外还有一些注释命令，在注释函数时比较有用如/param，具体的可查手册。
三、自定义配置文件
配置文件的定义要根据目的而定。以结合遇到的问题来说明选项的设置。
１）中文显示问题
中文输出文档设置，OUTPUT_LANGUAGE = Chinese
若项目标题为中文，PROJECT_NAME = 中文，即输出后的index.htm的主题目要显示为中文。则要求Doxyfile的编码方式为gbk，所以设置DOXYFILE_ENCODING = gbk。
源程序中的中文注释显示，这是最重要的。INPUT_ENCODING = gbk。
２）注释风格设置
JAVADOC_AUTOBRIEF = YES，可以使用上面的说明的注释方法。根据注释区中的第一个空行，自动提取简要说明。
四、常用命令
在注释时还有一些命令，可以起到不同的作用。
/param 注释函数参数时使用。
/todo 这个比较好，可以在文件中生成专门的列表，显示待进行的工作。
还有很多命令可以查其手册。
至此在不改动其它任何默认选项的情况下，已经可以生成非常漂亮的文档了。以后用到再继续补充。(12.17)
分享到：