便利的开发文档工具-doxygen

《便利的开发文档工具-doxygen》由会员上传分享，免费在线阅读，更多相关内容在工程资料-天天文库。

1、便利的开发文档工具-doxygen0.序言为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释，注释如何写，写多少等这些问题，很多程序员仍然没有答案。更头痛的是写文档，以及维护文档的问题，开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释，但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档，对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动转化为对应的文档。Doxygen是基于GP

2、L的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++,C,Java,IDL（Corba和Microsoft家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unixmanpage。有很多开源项目（包括前两篇文章介绍的log4cpp和CppUnit）都使用了doxygen文档系统。而国内的开发人员却使用的不多，这里从开发人员使用的角度介绍这个工具，使开发人员用最少的

3、代价尽快掌握这种技术，并结合这个工具探讨如何撰写注释的问题。以下以linux下的C++语言为例进行介绍，以下讨论基于doxygen1.3.3。1.doxygen使用步骤由于只是工具的使用，这里不介绍它的原理，直接从使用步骤开始。Doxygen的使用步骤非常简单。主要可以分为： 1）第一次使用需要安装doxygen的程序 2）生成doxygen配置文件 3）编码时，按照某种格式编写注释 4）生成对应文档doxygen的安装非常简单，linux下可以直接下载安装包运行即可，下载源代码编译安装也是比较通用的编译

4、安装命令。请参考其安装文档完成安装。Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件：doxygen-g [配置文件名]可以根据项目的具体需求修改配置文件中对应的项，具体的修改过程在下面介绍。修改过的配置文件可以作为以后项目的模板。让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。具体如何写doxygen认识的注释在第3节详细介绍。OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪？非常简单，运行下

5、面的命令，相应的文档就会产生在指定的目录中。  doxygen[配置文件名]需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。2.doxygen配置文件doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释'#'开始；tag=value[,value2…]；对于多值的情况可以使用tag+=value[,value2…]。对doxygen的配置文件的修改分为两类：一种就是输出选

6、项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。TAG 缺省值 含义PROJECT_NAME  项目名称PROJECT_NUMBER  可以理解为版本信息OUTPUT_DIRECTORY  输出文件到的目录，相对目录（doxygen运行目录）或者绝对目录INPUT  代码文件或者代码所在目录，使

7、用空格分割FILE_PATTERNS *.c*.cc*.cxx*.cpp*.c++*.java*.ii*.ixx*.ipp*.i++*.inl*.h*.hh*.hxx*.hpp*.h++*.idl*.odl 指定INPUT的目录中特定文件，如：*.cpp*.c*.hRECURSIVE NO 是否递归INPUT中目录的子目录EXCLUDE  在INPUT目录中需要忽略的子目录EXCLUDE_PATTERNS  明确指定的在INPUT目录中需要忽略的文件，如：FromOut*.cpp  OUTPUT_LANG

8、UAGE English 生成文档的语言，当前支持2、30种语言，国内用户可以设置为ChineseUSE_WINDOWS_ENCODING YES（win版本）NO（unix版本） 编码格式，默认即可。EXTRACT_ALL NO 为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释。类的私有成员和所有的静态项由EXTRACT_PRIVATE和EXTRACT_STATIC控制EXTRACT_PRI