学习用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++ 源代码文件和头文件。例如，请考虑以下代码片段：INPUT = /home/user1/project/kernel /home/user1/project/memory

在这里， doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有 多个子目录，那么只需指定根目录并把 <RECURSIVE> 标记设置为 Yes。

<FILE_PATTERNS>：在默认情况下，doxygen 会搜索具有典型 C/C++ 扩展 名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果 <FILE_PATTERNS> 标记没有 相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地 更新这个标记。例如，如果项目使用.c86 作为 C 文件扩展名，就应该在 <FILE_PATTERNS> 标记中添加这个扩展名。

<RECURSIVE>：如果源代 码层次结构是嵌套的，而且需要为所有层次上的C/C++ 文件生成文档，就把这个标记设置 为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如 果这个标记设置为 Yes，doxygen 就会递归地搜索整个层次结构并提取信息。

<EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也 要提取信息。必须把这个标记设置为 Yes。

<EXTRACT_PRIVATE>：把这个标 记设置为 Yes。否则，文档不包含类的私有数据成员。

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!