学习用 doxygen 生成源码文档
Arpan Sen
2008 年 10 月 13 日发布
维护用 C/C++
开发的遗留系统并添加新特性是一项艰难的任务。这涉及几方面的问题:理解现有的类层次结构和全局变量,不同的用户定义类型,以及函数调用图分析等等。本文在 C/C++
项目的上下文中通过示例讨论 doxygen 的几个特性。但是,doxygen 非常灵活,也可用于用 Python、Java、PHP 和其他语言开发的软件项目。本文的主要目的是帮助您从 C/C++
源代码提取出信息,但也简要描述了如何用 doxygen 定义的标记生成代码文档。
安装 doxygen
有两种获得 doxygen 的方法。可以下载预编译的可执行文件,也可以从 SVN 存储库下载源代码并自己编译。清单 1 演示的是后一种方法。
清单 1. 安装和构建 doxygen 源代码
1 2 3 4 5 6 7 |
|
注意,配置脚本把编译的源代码存储在 /home/user1/bin 中(进行编译后,会在 PATH 变量中添加这个目录),因为并非每个 UNIX® 用户都有写 /usr 文件夹的权限。另外,需要用 svn
实用程序下载源代码。
使用 doxygen 生成文档
使用 doxygen 生成源代码的文档需要执行三个步骤。
生成配置文件
在 shell 提示上,输入命令 doxygen -g
。这个命令在当前目录中生成一个可编辑的配置文件 Doxyfile。可以改变这个文件名,在这种情况下,应该调用 doxygen -g <user-specified file name>
,见 清单 2。
清单 2. 生成默认的配置文件
1 2 3 4 5 6 7 |
|
编辑配置文件
配置文件采用 <TAGNAME>
= <VALUE>
这样的结构,与 Make 文件格式相似。下面是最重要的标记:
<OUTPUT_DIRECTORY>
:必须在这里提供一个目录名,例如 /home/user1/documentation,这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名,doxygen 会以这个名称创建具有适当用户权限的目录。<INPUT>
:这个标记创建一个以空格分隔的所有目录的列表,这个列表包含需要生成文档的C/C++
源代码文件和头文件。例如,请考虑以下代码片段:1
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。否则,文档不包含类的私有数据成员。<EXTRACT_STATIC>
:把这个标记设置为 Yes。否则,文档不包含文件的静态成员(函数和变量)。
清单 3 给出一个 Doxyfile 示例。
清单 3. 包含用户提供的标记值的 doxyfile 示例
1 2 3 4 5 6 7 8 9 |
|
运行 doxygen
在 shell 提示下输入 doxygen Doxyfile
(或者已为配置文件选择的其他文件名)运行 doxygen。在最终生成 Hypertext Markup Language(HTML)和 Latex 格式(默认)的文档之前,doxygen 会显示几个消息。在生成文档期间,在 <OUTPUT_DIRECTORY>
标记指定的文件夹中,会创建两个子文件夹 html 和 latex。清单 4 是一个 doxygen 运行日志示例。
清单 4. doxygen 的日志输出
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
|
文档输出格式
除了 HTML 之外,doxygen 还可以生成几种输出格式的文档。可以让 doxygen 生成以下格式的文档:
- UNIX 手册页:把
<GENERATE_MAN>
标记设置为 Yes。在默认情况下,会在<OUTPUT_DIRECTORY>
指定的目录中创建 man子文件夹,生成的文档放在这个文件夹中。必须把这个文件夹添加到 MANPATH 环境变量中。 - Rich Text Format(RTF):把
<GENERATE_RTF>
标记设置为 Yes。把<RTF_OUTPUT>
标记设置为希望放置 .rtf 文件的目录;在默认情况下,文档放在 OUTPUT_DIRECTORY 中的 rtf 子文件夹中。要想支持跨文档浏览,应该把<RTF_HYPERLINKS>
标记设置为 Yes。如果设置这个标记,生成的 .rtf 文件会包含跨文档链接。 - Latex:在默认情况下,doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中,
<GENERATE_LATEX>
标记设置为 Yes。另外,<LATEX_OUTPUT>
标记设置为 Latex,这意味着会在 OUTPUT_DIRECTORY 中创建 latex 子文件夹并在其中生成 Latex 文件。 - Microsoft® Compiled HTML Help(CHM)格式:把
<GENERATE_HTMLHELP>
标记设置为 Yes。因为在 UNIX 平台上不支持这种格式,doxygen 只在保存 HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。 - Extensible Markup Language(XML)格式:把
<GENERATE_XML>
标记设置为 Yes。(注意,doxygen 开发团队还在开发 XML 输出)。
清单 5 提供的 Doxyfile 示例让 doxygen 生成所有格式的文档。
清单 5. 生成多种格式的文档的 Doxyfile
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
doxygen 中的特殊标记
doxygen 包含几个特殊标记。
C/C++ 代码的预处理
为了提取信息,doxygen 必须对 C/C++
代码进行预处理。但是,在默认情况下,它只进行部分预处理 —— 计算条件编译语句(#if…#endif
),但是不执行宏展开。请考虑 清单 6 中的代码。
清单 6. 使用宏的 C++ 代码示例
1 2 3 4 5 6 7 8 9 10 11 12 |
|
通过源代码中定义的 <USE_ROPE>
,doxygen 生成的文档如下:
1 2 3 4 5 6 |
|
在这里可以看到 doxygen 执行了条件编译,但是没有对 STRING
执行宏展开。Doxyfile 中的 <ENABLE_PREPROCESSING>
标记在默认情况下设置为 Yes。为了执行宏展开,还应该把 <MACRO_EXPANSION>
标记设置为 Yes。这会使 doxygen 产生以下输出:
1 2 3 4 5 6 |
|
如果把 <ENABLE_PREPROCESSING>
标记设置为 No,前面源代码的 doxygen 输出就是:
1 2 |
|
注意,文档现在没有定义,而且不可能推导出 STRING
的类型。因此,总是应该把 <ENABLE_PREPROCESSING>
标记设置为 Yes。
在文档中,可能希望只展开特定的宏。为此,除了把 <ENABLE_PREPROCESSING>
和 <MACRO_EXPANSION>
标记设置为 Yes 之外,还必须把 <EXPAND_ONLY_PREDEF>
标记设置为 Yes(这个标记在默认情况下设置为 No),并在 <PREDEFINED>
或 <EXPAND_AS_DEFINED>
标记中提供宏的细节。请考虑 清单 7 中的代码,这里只希望展开宏 CONTAINER
。
清单 7. 包含多个宏的 C++ 源代码
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
清单 8 给出配置文件。
清单 8. 允许有选择地展开宏的 Doxyfile
1 2 3 4 5 |
|
下面的 doxygen 输出只展开了 CONTAINER
:
1 2 3 4 5 6 7 |
|
注意,只有 CONTAINER
宏被展开了。在 <MACRO_EXPANSION>
和 <EXPAND_ONLY_PREDEF>
都设置为 Yes 的情况下,<EXPAND_AS_DEFINED>
标记只选择展开等号操作符右边列出的宏。
对于预处理过程,要注意的最后一个标记是 <PREDEFINED>
。就像用 -D
开关向 C++ 编译器传递预处理器定义一样,使用这个标记定义宏。请考虑 清单 9 中的 Doxyfile。
清单 9. 定义了宏展开标记的 Doxyfile
1 2 3 4 5 6 |
|
下面是 doxygen 生成的输出:
1 2 3 4 5 6 7 8 |
|
在使用 <PREDEFINED>
标记时,宏应该定义为 <macro name>=<value>
形式。如果不提供值,比如简单的 #define
,那么只使用 <macro name>=<spaces>
即可。多个宏定义以空格或反斜杠(\
)分隔。
从文档生成过程中排除特定文件或目录
在 Doxyfile 中的 <EXCLUDE>
标记中,添加不应该为其生成文档的文件或目录(以空格分隔)。因此,如果提供了源代码层次结构的根,并要跳过某些子目录,这将非常有用。例如,如果层次结构的根是 src_root,希望在文档生成过程中跳过 examples/ 和 test/memoryleaks 文件夹,Doxyfile 应该像 清单 10 这样。
清单 10. 使用 EXCLUDE 标记的 Doxyfile
1 2 3 |
|
生成图形和图表
在默认情况下,Doxyfile 把 <CLASS_DIAGRAMS>
标记设置为 Yes。这个标记用来生成类层次结构图。要想生成更好的视图,可以从 Graphviz 下载站点 下载 dot 工具。Doxyfile 中的以下标记用来生成图表:
<CLASS_DIAGRAMS>
:在 Doxyfile 中这个标记默认设置为 Yes。如果这个标记设置为 No,就不生成继承层次结构图。<HAVE_DOT>
:如果这个标记设置为 Yes,doxygen 就使用 dot 工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。注意,如果这个标记设置为 Yes,<CLASS_DIAGRAMS>
标记就无效了。<CLASS_GRAPH>
:如果<HAVE_DOT>
标记和这个标记同时设置为 Yes,就使用dot
生成继承层次结构图,而且其外观比只使用<CLASS_DIAGRAMS>
时更丰富。<COLLABORATION_GRAPH>
:如果<HAVE_DOT>
标记和这个标记同时设置为 Yes,doxygen 会生成协作图(还有继承图),显示各个类成员(即包含)及其继承层次结构。
清单 11 提供一个使用一些数据结构的示例。注意,在配置文件中 <HAVE_DOT>
、<CLASS_GRAPH>
和 <COLLABORATION_GRAPH>
标记都设置为 Yes。
清单 11. C++ 类和结构示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
图 1 给出 doxygen 的输出。
图 1. 使用 dot 工具生成的类继承图和协作图
代码文档样式
到目前为止,我们都是使用 doxygen 从原本没有文档的代码中提取信息。但是,doxygen 也鼓励使用文档样式和语法,这有助于生成更详细的文档。本节讨论 doxygen 鼓励在 C/C++
代码中使用的一些常用标记。更多信息参见 参考资料。
每个代码元素有两种描述:简短的和详细的。简短描述通常是单行的。函数和类方法还有第三种描述体内描述(in-body description),这种描述把在函数体中找到的所有注释块集中在一起。比较常用的一些 doxygen 标记和注释样式如下:
- 简短描述:使用单行的
C++
注释,或使用<\brief>
标记。 - 详细描述:使用 JavaDoc 式的注释
/** … test … */
(注意开头的两个星号 [*
])或 Qt 式的注释/*! … text … */
。 - 体内描述:类、结构、联合体和名称空间等
C++
元素都有自己的标记,比如<\class>
、<\struct>
、<\union>
和<\namespace>
。
为了为全局函数、变量和枚举类型生成文档,必须先对对应的文件使用 <\file>
标记。清单 12 给出的示例包含用于四种元素的标记:函数标记(<\fn>
)、函数参数标记(<\param>
)、变量名标记(<\var>
)、用于 #define
的标记(<\def>
)以及用来表示与一个代码片段相关的问题的标记(<\warning>
)。
清单 12. 典型的 doxygen 标记及其使用方法
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
下面是生成的文档:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
结束语
本文讨论如何用 doxygen 从遗留的 C/C++
代码提取出大量相关信息。如果用 doxygen 标记生成代码文档,doxygen 会以容易阅读的格式生成输出。只要以适当的方式使用,doxygen 就可以帮助任何开发人员维护和管理遗留系统。
相关主题
- 您可以参阅本文在 developerWorks 全球站点上的 英文原文 。
- doxygen 站点 包含关于 doxygen 的非常有价值的手册和几篇文章。
- 下载 doxygen。
- 下载 dot 实用程序。
- AIX and UNIX 专区:developerWorks 的“AIX and UNIX 专区”提供了大量与 AIX 系统管理的所有方面相关的信息,您可以利用它们来扩展自己的 UNIX 技能。
- AIX and UNIX 新手入门:访问“AIX and UNIX 新手入门”页面可了解更多关于 AIX 和 UNIX 的内容。