作者: davygeek
2017-01-17 09:43:33
使用doxygen 生成源代码的文档是相当方便的，本文就简单整理下doxygen的使用说明。
1.安装
关于安装的问题不做特殊的说明，这里直接使用命令安装，源码安装不做介绍。
ubuntu:
sudo apt-get install doxygen
centos
sudo yum install doxygen
2.配置文件配置
关于doxygen主要的部分就在于配置文件的配置， doxygen相当强大，所以配置文件内容有点多。这里只介绍一部分，大家有兴趣可以继续深入研究。
(1) 重要标记
配置文件采用 = 这样的结构，与 Make 文件格式相似。下面是最重要的标记：
：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。
：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如，请考虑以下代码片段：
INPUT = /home/user1/project/kernel /home/user1/project/memory
在这里，doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把 标记设置为 Yes。
：在默认情况下，doxygen 会搜索具有典型 C/C++ 扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果 标记没有相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为 C 文件扩展名，就应该在 标记中添加这个扩展名。
：如果源代码层次结构是嵌套的，而且需要为所有层次上的 C/C++ 文件生成文档，就把这个标记设置为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为 Yes，doxygen 就会递归地搜索整个层次结构并提取信息。
：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为 Yes。
：把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。
：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。
(2) 文档输出格式
除了 HTML 之外，doxygen 还可以生成几种输出格式的文档。可以让 doxygen 生成以下格式的文档：
UNIX 手册页：把 标记设置为 Yes。在默认情况下，会在 指定的目录中创建 man 子文件夹，生成的文档放在这个文件夹中。必须把这个文件夹添加到 MANPATH 环境变量中。
Rich Text Format（RTF）：把 标记设置为 Yes。把 标记设置为希望放置 .rtf 文件的目录；在默认情况下，文档放在OUTPUT_DIRECTORY 中的 rtf 子文件夹中。要想支持跨文档浏览，应该把 标记设置为 Yes。如果设置这个标记，生成的 .rtf文件会包含跨文档链接。
Latex：在默认情况下，doxygen 生成 Latex 和 HTML 格式的文档。在默认的 Doxyfile 中， 标记设置为 Yes。另外， 标记设置为 Latex，这意味着会在 OUTPUT_DIRECTORY 中创建 latex 子文件夹并在其中生成 Latex 文件。
Microsoft® Compiled HTML Help（CHM）格式：把 标记设置为 Yes。因为在 UNIX 平台上不支持这种格式，doxygen 只在保存HTML 文件的文件夹中生成一个 index.hhp 文件。您必须通过 HTML 帮助编译器把这个文件转换为 .chm 文件。
Extensible Markup Language（XML）格式：把 标记设置为 Yes。（注意，doxygen 开发团队还在开发 XML 输出）。
(3) 图形和图标生成
在默认情况下，Doxyfile 把 标记设置为 Yes。这个标记用来生成类层次结构图。要想生成更好的视图，可以从 Graphviz 下载站点（http://www.graphviz.org/） 下载dot 工具。Doxyfile 中的以下标记用来生成图表：
：在 Doxyfile 中这个标记默认设置为 Yes。如果这个标记设置为 No，就不生成继承层次结构图。
：如果这个标记设置为 Yes，doxygen 就使用 dot 工具生成更强大的图形，比如帮助理解类成员及其数据结构的协作图。注意，如果这个标记设置为 Yes， 标记就无效了。
：如果 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图，而且其外观比只使用 时更丰富。
：如果 标记和这个标记同时设置为 Yes，doxygen 会生成协作图（还有继承图），显示各个类成员（即包含）及其继承层次结构。
(4) 代码文档样式
每个代码元素有两种描述：简短的和详细的。简短描述通常是单行的。函数和类方法还有第三种描述体内描述（in-body description），这种描述把在函数体中找到的所有注释块集中在一起。比较常用的一些 doxygen 标记和注释样式如下：
简短描述：使用单行的 C++ 注释，或使用 <\brief> 标记。
详细描述：使用 JavaDoc 式的注释 /** … test … */（注意开头的两个星号 [*]）或 Qt 式的注释 /*! … text … */。
体内描述：类、结构、联合体和名称空间等 C++ 元素都有自己的标记，比如 <\class>、<\struct>、<\union> 和 <\namespace>。
为了为全局函数、变量和枚举类型生成文档，必须先对对应的文件使用 <\file> 标记。清单 12 给出的示例包含用于四种元素的标记：函数标记（<\fn>）、函数参数标记（<\param>）、变量名标记（<\var>）、用于 #define 的标记（<\def>）以及用来表示与一个代码片段相关的问题的标记（<\warning>）。
一下是一些doxygen自建的命令，可以在代码注释中加入：
@addtogroup 添加到一个组。
@brief概要信息
@deprecated 已废弃函数
@details详细描述
@note开始一个段落，用来描述一些注意事项
@par开始一个段落，段落名称描述由你自己指定
@param标记一个参数的意义
@code .. @endcode 包含一段代码
@fn函数说明
@ingroup 加入到一个组
@return描述返回意义
@retval描述返回值意义
@include 包含文件
3.其他
doxygen功能还是很强大的，对于c++和java的代码结构生成以及图标生成很好用;可以很方便的看到代码结构，对于c暂时没有生成出对应的图表，后续还需要继续研究下。