学习用doxygen生成源码文档

从文档生成过程中排除特定文件或目录

在 Doxyfile 中的 <EXCLUDE> 标记中，添加不应该为其生成文档的文件或目录（以空格分隔）。因此 ，如果提供了源代码层次结构的根，并要跳过某些子目录，这将非常有用。例如，如果层 次结构的根是src_root，希望在文档生成过程中跳过 examples/ 和 test/memoryleaks 文件夹，Doxyfile 应该像 清单 10 这样。

清单 10. 使用EXCLUDE 标记的 Doxyfile

INPUT = /home/user1/src_root
EXCLUDE = /home/user1/src_root/examples /home/user1/src_root/test/memoryleaks
…

生成图形和图表

在默认情况下，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++ 类和结构示例

struct D {
　int d;
};
class A {
　int a;
};
class B : public A {
　int b;
};
class C : public B {
　int c;
　D d;
};

图 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 标记及其使用方法

/*! \file globaldecls.h
      \brief Place t

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