学习使用 doxygen 生成源码文档

维护用 C/C++ 开发的遗留系统并添加新特性是一项艰难的任务。幸运的是，doxygen 可以帮助您完成这个任务。doxygen 是一种用于 C/C++、Java™、Python 和其他编程语言的文档系统。本文在 C/C++ 项目的上下文中讨论 doxygen 的特性，以及如何用 doxygen 定义的标记生成代码文档。

维护用 C/C++ 开发的遗留系统并添加新特性是一项艰难的任务。这涉及几方面的问题：理解现有的类层次结构和全局变量，不同的用户定义类型，以及函数调用图分析等等。本文在 C/C++ 项目的上下文中通过示例讨论 doxygen 的几个特性。但是，doxygen 非常灵活，也可用于用 Python、Java、PHP 和其他语言开发的软件项目。本文的主要目的是帮助您从 C/C++ 源代码提取出信息，但也简要描述了如何用 doxygen 定义的标记生成代码文档。

安装 doxygen

有两种获得 doxygen 的方法。可以下载预编译的可执行文件，也可以从 SVN 存储库下载源代码并自己编译。清单 1 演示的是后一种方法。

清单 1. 安装和构建 doxygen 源代码

bash-2.05$ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn bash-2.05$ cd doxygen-svn bash-2.05$ ./configure –prefix=/home/user1/bin bash-2.05$ make bash-2.05$ make install

注意，配置脚本把编译的源代码存储在 /home/user1/bin 中（进行编译后，会在 PATH 变量中添加这个目录），因为并非每个 UNIX® 用户都有写 /usr 文件夹的权限。另外，需要用 svn 实用程序下载源代码。

回页首

使用 doxygen 生成文档

使用 doxygen 生成源代码的文档需要执行三个步骤。

生成配置文件

在 shell 提示上，输入命令 doxygen -g 。这个命令在当前目录中生成一个可编辑的配置文件 Doxyfile。可以改变这个文件名，在这种情况下，应该调用 doxygen -g <user-specified file name>，见 清单 2。

清单 2. 生成默认的配置文件

bash-2.05b$ doxygen -g Configuration file 'Doxyfile' created. Now edit the configuration file and enter doxygen Doxyfile to generate the documentation for your project bash-2.05b$ ls Doxyfile Doxyfile

编辑配置文件

配置文件采用 <TAGNAME> = <VALUE> 这样的结构，与 Make 文件格式相似。下面是最重要的标记：

• <OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。
• <INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如，请考虑以下代码片段：

本文转自IBM Developerworks中国

      请点击此处查看全文