doxygen 生成源码文档

使用doxygen 生成源代码的文档是相当方便的，本文就简单整理下doxygen的使用说明

1. 安装

　关于安装的问题不做特殊的说明，这里直接使用命令安装， 源码安装不做介绍

ubuntu:　

sudo apt-get install doxygen

centos

sudo yum install doxygen

2. 配置文件配置

　关于doxygen主要的部分就在于配置文件的配置， doxygen相当强大，所以配置文件内容有点多。这里只介绍一部分，大家有兴趣可以继续深入研究

　(1) 重要标记

　　配置文件采用 <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。否则，文档不包含类的私有数据成员。

　　<EXTRACT_STATIC>：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。

(2) 文档输出格式　　

　　除了 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 输出）。

(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 会生成协作图（还有继承图），显示各个类成员（即包含）及其继

　　承层次结构。

(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暂时没有生成出对应的图表，后续还需要继续研究下。 后续get到其他技能继续在后面补充