为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了
程序的可维护性、可读性编码的同时写注释的说法,但对哪些地方应该写注释,
注释如何写,写多少等这些问题,很多程序员仍然没有答案。更头痛的是写文
档,以及维护文档的问题,开发人员通常可以忍受编写或者改动代码时编写或
者修改对 应的注释,但之后需要修正相应的文档却比较困难。如果能从注释直
接转化成文档,对开发人员无疑是一种福音。而 doxygen 就能把遵守某种格
式的注释自动 转化为对应的文档。
Doxygen 是基于 GPL 的开源项目,是一个非常优秀的文档系统,当前支持在
大多数 unix(包括 linux),windows 家族,Mac 系统 上运行,完全支持
C++, C, Java, IDL(Corba 和 Microsoft 家族)语言,部分支持 PHP 和 C#
语言,输出格式包括 HTML、latex、RTF、ps、PDF、压缩的 HTML 和 unix
manpage。有很多开源项目(包括前两篇文章介绍的 log4cpp 和 CppUnit)
都使用了 doxygen 文档系统。而国内的开发人员却使用的不 多,这里从开发
人员使用的角度介绍这个工具,使开发人员用最少的代价尽快掌握这种技术,
并结合这个工具探讨如何撰写注释的问题。以下以 linux 下的 C++语言为例进
行介绍,以下讨论基于 doxygen1.3.3。
1. doxygen 使用步骤
由于只是工具的使用,这里不介绍它的原理,直接从使用步骤开始。Doxygen
的使用步骤非常简单。主要可以分为:
1)第一次使用需要安装 doxygen 的程序
2)生成 doxygen 配置文件
3)编码时,按照某种格式编写注释
4)生成对应文档
doxygen 的安装非常简单, linux 下可以直接下载安装包运行即可,下载源代
码编译安装也是比较通用的编译安装命令。请参考其安装文档完成安装。
Doxygen 在生成文档时可以定义项目属性以及文档生成过程中的很多选项,
使用下面命令能够产生一个缺省的配置文件:
doxygen -g [配置文件名]
可以根据项目的具体需求修改配置文件中对应的项,具体的修改过程在下面介
绍。修改过的配置文件可以作为以后项目的模板。
让 doxygen 自动产生文档,平常的注释风格可不行,需要遵循 doxygen 自己
的格式。具体如何写 doxygen 认识的注释在第 3 节详细介绍。
OK,代码编完了,注释也按照格式写好了,最后的文档是如何的哪?非常简单,
运行下面的命令,相应的文档就会产生在指定的目录中。
doxygen [配置文件名]
需要注意的是 doxygen 并不处理所有的注释,doxygen 重点关注与程序结构
有关的注释,比如:文件、类、结构、函数、变量、宏等注释,而忽略函数内
变量、代码等的注释。
评论1