doxygen参考
合集下载
相关主题
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
声明分组之后，如果要使某个实体归属某一分组，需要使用 ingroup 命令。 避免在每个成员之前都使用 ingroup 命令，可以将 member 用@{和@}封装起来。
/** * \ingroup A */ extern int VarInA; /** * \defgroup IntVariables Global integer variables */ /*@{*/ /** an integer variable */ extern int IntegerVariable; /*@}*/ .... /** * \defgroup Variables Global variables */ /*@{*/ /** a variable in group A */ int VarInA; int IntegerVariable; /*@}*/
功能目前仅有 HTML 和 RTF 格式支持。 • 当 COLLABORATION_GRAPH 设置为 YES 时，会为每个归档类或结构绘制基类继
承关系图和使用关系图。 • 当 CALL_GRAPH 设置为 YES 时，会为每个函数显示一幅直接或间接调用关系图。
虽然如此，我们还是要理解常见的各个 Tag 的含义。在 Doxywizard 中，可 以看到这些 Tag 以自明的方式命名，我们大致可以从名称中看出其作用。这 些 Tag 被 Doxywizard 大致分为几类，其中 HTML 到 PerlMod 是输出文件种类设置， Project 是 Doxygen 工程设置，Build 是 编译类选项，Messages 为出错或异常 选项，Input 为输入源选项，等等。
分组
Doxygen 有两种分组机制。第一种是全局地为每一个组创建一个网页，此时 分组被称为"module"；第二种是用于复合实体中的成员列表，此时分组被 称为 "member group"。Module 是一种把内容在单个网页上分组的方法。分组可以包 括 files，namespace，classes，functions，variables，enums，typedefs 和 defines，也可以包含 其它分组。复合实体（compound entities）如类、文件、
图 2 Doxywizard
注释
Doxygen 规定了进行注释的一些格式，正确的注释才能使 Doxygen 生成文档。 第一个代码条目，都有两种描述：简要描述和详细描述，两者都是可选的。简要 描述只有一行，而详细描述则提供更长、更仔细的描述，Doxygen 只允许有一个 简要描述和详细描述。
在 Doxygen 中，一般只会处理与程序结构相关的注释，函数内部的注释通 常不做处理。对于详细描述来说，有下面几种表示方式。
点击查看大图
图 1 Doxygen 网站上给出的 Doxygen 信息流图
配置文件
每一个 Doxygen 工程都有一个后缀为.cfg 的配置文件，用来保存所有的设 置。配置文件的格式与 autoexec.bat、config.sys 等文 件相似，是由名称/值 对组成的 ASCII 码，会由 doxygen 命令来解析。为了简化创建和修改配置文件， Doxygen 可以在命令行方式下加上参数-g 自动创建模板文件。 doxygen -g <config-file>
编译源码
gunzip doxygen-$VERSION.src.tar.gz tar xf doxygen-$VERSION.src.tar sh ./configure，或者 configure --platform platform-type （略去直接使用 configure 需要平台检测的过程，平台类型在 PLATFORMS 文件中 列出）， configure --with-doxywizard（GUI 前端选项） make，或者 make docs（创建 HTML 格式的手册），make pdf（创建 PDF 格式的 手册）
安装二进制版本
./configure make install
二进制文件安装目录是<prefix>/bin，其中<prefix>缺省为/usr，可以通过 configure 的参数 --prefix 修改其值。使用 make install_docs 可以把文档和 例子安装在目录<docdir>/doxygen，其中<docdir>缺省 为 <prefix>/share/doc/packages，可以通过 configure 的参数--docdir 修改其值。 doxygen 是 bin 目录下的一个命令行程序，它是 Doxygen 的核心工具，完成文档 的转换和生成工作。
使用 Doxygen 构建文档系统
如果您这次还没来得及使用老式的 Help Workshop 为您的 Web 应用构建文档系统 的话，那么，何不尝试一下 Doxygen，需知"The proof of the pudding lies in the eating"。
Doxygen 是什么？
Doxygen 是一种开源跨平台的，以类似 JavaDoc 风格描述的文档系统，完全 支持 C、C++、Java、Objective-C 和 IDL 语言，部分支持 PHP、 C#。注释的语 法与 Qt-Doc、KDoc 和 JavaDoc 兼容。Doxgen 可以从一套归档源文件开始，生成 HTML 格式的在线类浏览器，或离线的 LATEX、RTF 参考手册。对于未归档的源文 件，也可以通过配置 Doxygen 来提取代码结构。或者借助自动生成的包含依赖图 （include dependency graphs）、继承图（inheritance diagram）以及协作图 （collaboration diagram）来可视化文档之间的关系。Doxygen 生成的帮助文 档的格式可以是 CHM、RTF、PostScript、PDF、HTML 和 Unix man page 等。
如果要把不同的类型归入同一分组内，就要使用 Member group，它的定义方法 如下：
//@{ ...
//@} 或者 /*@{*/
... /*@}*/
Member group 不可以嵌套。
图表
Doxygen 里有内置生成 C++类层次图的功能。它使用贝尔实验室开发的 graphviz 1.5 中的工具"dot"来生成更高级的图表。使用这个工具时，要将配置 选项 HAVE_DOT 设为 YES。
下面章节中也涉及到一些命令的使用，其它的命令可以查阅 Doxygen 用户手册。
列表
Doxygen 有许多方法可以创建项目列表。
使用"-"在每行开始之前打头，使用"."可以结束一个列表，开始新的段落。使用 这种方法要严格对齐。 /** * - 表项一 * - 子项一 * - 子项二 *. *. */ 在文档块中使用 HTML 命令。这种方法不需要严格对齐。 /*! * <ul> * <li> 表项一 * <ol> * <li> 子项一 * <li> 子项二 * </ol> * <li> 表项二 * </ul> */
命令
Doxygen 支持的指令非常多，主要作用是控制输出文档的排版格式。命令以 "\"或"@"号开始。
一些命令可以有多个参数，一些命令只有一个参数。参数周围的括号使用是有含 义的：
• <>号表示参数是单个词。 • ()号表示参数一直会到行尾。 • {}号表示参数会扩展到下一段落。 • []号表示参数是可选的。
Doxygen 在 Linux 上开发，但也可以在其它的 Unix 平台下运行。而且，Windows 9x/NT 平台下也有对应的可执行版本。
安装 Doxygen
首先，去 Doxygen 网站上找到最新版本的 Doxygen。有二进制或源码两种版 本，如果不想重头编译，下载二进制版本安装即可。在 Linux 下，源码编译需要 perl 和 Gnu 工具 flex、bison、make 的支持。在 Windows 下，二进制版本勿需 安装，而源码编译所需支持工具较多。我们仅讲述 Linux 下的 Doxygen 的源码编 译以及二进制版本安装过程。
Doxygen 的处理流程
图 1 是 Doxygen 网站上给出的 Doxygen 处理工具以及它们之间的信息流。
从图中可以看出，Doxygen 可执行程序位于正中，所有的流程都围绕着它进 行。左侧图标表示 Doxygen 的输入可以是源文件，或者是定制的头文件、图像、 注解等。Doxygen 图标上部是配置文件，由 Doxywizard 处理，下部是 Tag 文件， 由 Doxytag 处理。后面是 Doxygen 输出文件的类型，依次是 XML、Latex、Man pages、 RTF 和 HTML，可处理类型图标之后是进行进一步转换所需的工具。
忽略<config-file>将会生成一个名为 Doxyfile 的缺省文件，如果 <config-file>已经存在，会被 Doxygen 改名为<config-file>.bak。
实际上，我们根本就不需要用一般的编辑器来编辑配置文件，Doxygen 提供 了一个辅助工具 Doxywizard。Doxywizard 是 Doxygen 的 GUI 前台，用户可以能 过它来读写配置文件，省却了手工配置的麻烦。基本上，在 Doxywizard 中可以 完成 Doxygen 的绝大多数工作，而且 Doxygen 也可以在由 Doxywizard 启动，这 样就使得整个过程比较连贯。
• 当 GRAPHICAL_HIERARCHY 设置为 YES 时，将会绘制一个图形表示的类图结构。 • 当 CLASS_GRAPH 设置为 YES 时，会为每个归档的类创建一张图表示其直接或间
接的继承关系。 • 当 INCLUDE_GRAPH 设置为 YES 时，会为每个归档文件创建一幅包含依赖图，此
上面这些命令都是有优先级的，doxygen 会根据优先级将实体放入具有最高 优先级的分组之中。它们的优先级顺序 是：ingroup，defgroup，addtogroup， weakgroup。weakgroup 类似一个低优先级的 addtogroup。在.h 文件中可以使用 高优先级的命令定义层次结构，在.c 文件中\weakgroup 就不需要准确遵循.h 文 件中定义的层次结构。
Baidu Nhomakorabea
JavaDoc 风格，中间的"*"号可选。 /** * 注释 */ Qt 风格，中间的"*"号可选。 /*! * 注释 */ C++风格的变体，或者最后一个"/"改为"！"也可以。 /// 单行注释 /// 注释 /// 更加显著的表示。 /////////////////////////////////////////// /// 注释 /////////////////////////////////////////// 简要描述亦有多种表示方式。 在上述注释块中使用\brief 命令，详细注释在空行之后开始。 /*! \brief 简要描述 * 继续 * * 详细注释 */ JAVADOC_AUTOBRIEF 设置为 YES 后，在 JavaDoc 风格的注释中，第一个点号之前 的内容被自动设置为简要描述。 对于多行 C++变体，这个选项亦会起到相同的作用。 /** 简要描述.详细描述 * 注释 */ C++变体风格。 /// 简要描述 /* 详细描述 */
命名空间等可以分布在多个分组中，而成员实体（member）如变量、函数、typedef 等只能归属于一个分组。
定义分组的方法是在特殊注释块中使用命令\defgroup 和\addtogroup。 defgroup 的格式如下：
\defgroup <唯一标识名> （中间可以有空格的标题）
两次使用同一标识名，在 doxygen 解析的时候会出现错误。命令 addtogroup 与 defgroup 不同的地方在于，如果使用了同一标识，则会在改组中加入新的项， 如果标识不重复，则会创建分组。addtogroup 中的标题是可选的。
/** * \ingroup A */ extern int VarInA; /** * \defgroup IntVariables Global integer variables */ /*@{*/ /** an integer variable */ extern int IntegerVariable; /*@}*/ .... /** * \defgroup Variables Global variables */ /*@{*/ /** a variable in group A */ int VarInA; int IntegerVariable; /*@}*/
功能目前仅有 HTML 和 RTF 格式支持。 • 当 COLLABORATION_GRAPH 设置为 YES 时，会为每个归档类或结构绘制基类继
承关系图和使用关系图。 • 当 CALL_GRAPH 设置为 YES 时，会为每个函数显示一幅直接或间接调用关系图。
虽然如此，我们还是要理解常见的各个 Tag 的含义。在 Doxywizard 中，可 以看到这些 Tag 以自明的方式命名，我们大致可以从名称中看出其作用。这 些 Tag 被 Doxywizard 大致分为几类，其中 HTML 到 PerlMod 是输出文件种类设置， Project 是 Doxygen 工程设置，Build 是 编译类选项，Messages 为出错或异常 选项，Input 为输入源选项，等等。
分组
Doxygen 有两种分组机制。第一种是全局地为每一个组创建一个网页，此时 分组被称为"module"；第二种是用于复合实体中的成员列表，此时分组被 称为 "member group"。Module 是一种把内容在单个网页上分组的方法。分组可以包 括 files，namespace，classes，functions，variables，enums，typedefs 和 defines，也可以包含 其它分组。复合实体（compound entities）如类、文件、
图 2 Doxywizard
注释
Doxygen 规定了进行注释的一些格式，正确的注释才能使 Doxygen 生成文档。 第一个代码条目，都有两种描述：简要描述和详细描述，两者都是可选的。简要 描述只有一行，而详细描述则提供更长、更仔细的描述，Doxygen 只允许有一个 简要描述和详细描述。
在 Doxygen 中，一般只会处理与程序结构相关的注释，函数内部的注释通 常不做处理。对于详细描述来说，有下面几种表示方式。
点击查看大图
图 1 Doxygen 网站上给出的 Doxygen 信息流图
配置文件
每一个 Doxygen 工程都有一个后缀为.cfg 的配置文件，用来保存所有的设 置。配置文件的格式与 autoexec.bat、config.sys 等文 件相似，是由名称/值 对组成的 ASCII 码，会由 doxygen 命令来解析。为了简化创建和修改配置文件， Doxygen 可以在命令行方式下加上参数-g 自动创建模板文件。 doxygen -g <config-file>
编译源码
gunzip doxygen-$VERSION.src.tar.gz tar xf doxygen-$VERSION.src.tar sh ./configure，或者 configure --platform platform-type （略去直接使用 configure 需要平台检测的过程，平台类型在 PLATFORMS 文件中 列出）， configure --with-doxywizard（GUI 前端选项） make，或者 make docs（创建 HTML 格式的手册），make pdf（创建 PDF 格式的 手册）
安装二进制版本
./configure make install
二进制文件安装目录是<prefix>/bin，其中<prefix>缺省为/usr，可以通过 configure 的参数 --prefix 修改其值。使用 make install_docs 可以把文档和 例子安装在目录<docdir>/doxygen，其中<docdir>缺省 为 <prefix>/share/doc/packages，可以通过 configure 的参数--docdir 修改其值。 doxygen 是 bin 目录下的一个命令行程序，它是 Doxygen 的核心工具，完成文档 的转换和生成工作。
使用 Doxygen 构建文档系统
如果您这次还没来得及使用老式的 Help Workshop 为您的 Web 应用构建文档系统 的话，那么，何不尝试一下 Doxygen，需知"The proof of the pudding lies in the eating"。
Doxygen 是什么？
Doxygen 是一种开源跨平台的，以类似 JavaDoc 风格描述的文档系统，完全 支持 C、C++、Java、Objective-C 和 IDL 语言，部分支持 PHP、 C#。注释的语 法与 Qt-Doc、KDoc 和 JavaDoc 兼容。Doxgen 可以从一套归档源文件开始，生成 HTML 格式的在线类浏览器，或离线的 LATEX、RTF 参考手册。对于未归档的源文 件，也可以通过配置 Doxygen 来提取代码结构。或者借助自动生成的包含依赖图 （include dependency graphs）、继承图（inheritance diagram）以及协作图 （collaboration diagram）来可视化文档之间的关系。Doxygen 生成的帮助文 档的格式可以是 CHM、RTF、PostScript、PDF、HTML 和 Unix man page 等。
如果要把不同的类型归入同一分组内，就要使用 Member group，它的定义方法 如下：
//@{ ...
//@} 或者 /*@{*/
... /*@}*/
Member group 不可以嵌套。
图表
Doxygen 里有内置生成 C++类层次图的功能。它使用贝尔实验室开发的 graphviz 1.5 中的工具"dot"来生成更高级的图表。使用这个工具时，要将配置 选项 HAVE_DOT 设为 YES。
下面章节中也涉及到一些命令的使用，其它的命令可以查阅 Doxygen 用户手册。
列表
Doxygen 有许多方法可以创建项目列表。
使用"-"在每行开始之前打头，使用"."可以结束一个列表，开始新的段落。使用 这种方法要严格对齐。 /** * - 表项一 * - 子项一 * - 子项二 *. *. */ 在文档块中使用 HTML 命令。这种方法不需要严格对齐。 /*! * <ul> * <li> 表项一 * <ol> * <li> 子项一 * <li> 子项二 * </ol> * <li> 表项二 * </ul> */
命令
Doxygen 支持的指令非常多，主要作用是控制输出文档的排版格式。命令以 "\"或"@"号开始。
一些命令可以有多个参数，一些命令只有一个参数。参数周围的括号使用是有含 义的：
• <>号表示参数是单个词。 • ()号表示参数一直会到行尾。 • {}号表示参数会扩展到下一段落。 • []号表示参数是可选的。
Doxygen 在 Linux 上开发，但也可以在其它的 Unix 平台下运行。而且，Windows 9x/NT 平台下也有对应的可执行版本。
安装 Doxygen
首先，去 Doxygen 网站上找到最新版本的 Doxygen。有二进制或源码两种版 本，如果不想重头编译，下载二进制版本安装即可。在 Linux 下，源码编译需要 perl 和 Gnu 工具 flex、bison、make 的支持。在 Windows 下，二进制版本勿需 安装，而源码编译所需支持工具较多。我们仅讲述 Linux 下的 Doxygen 的源码编 译以及二进制版本安装过程。
Doxygen 的处理流程
图 1 是 Doxygen 网站上给出的 Doxygen 处理工具以及它们之间的信息流。
从图中可以看出，Doxygen 可执行程序位于正中，所有的流程都围绕着它进 行。左侧图标表示 Doxygen 的输入可以是源文件，或者是定制的头文件、图像、 注解等。Doxygen 图标上部是配置文件，由 Doxywizard 处理，下部是 Tag 文件， 由 Doxytag 处理。后面是 Doxygen 输出文件的类型，依次是 XML、Latex、Man pages、 RTF 和 HTML，可处理类型图标之后是进行进一步转换所需的工具。
忽略<config-file>将会生成一个名为 Doxyfile 的缺省文件，如果 <config-file>已经存在，会被 Doxygen 改名为<config-file>.bak。
实际上，我们根本就不需要用一般的编辑器来编辑配置文件，Doxygen 提供 了一个辅助工具 Doxywizard。Doxywizard 是 Doxygen 的 GUI 前台，用户可以能 过它来读写配置文件，省却了手工配置的麻烦。基本上，在 Doxywizard 中可以 完成 Doxygen 的绝大多数工作，而且 Doxygen 也可以在由 Doxywizard 启动，这 样就使得整个过程比较连贯。
• 当 GRAPHICAL_HIERARCHY 设置为 YES 时，将会绘制一个图形表示的类图结构。 • 当 CLASS_GRAPH 设置为 YES 时，会为每个归档的类创建一张图表示其直接或间
接的继承关系。 • 当 INCLUDE_GRAPH 设置为 YES 时，会为每个归档文件创建一幅包含依赖图，此
上面这些命令都是有优先级的，doxygen 会根据优先级将实体放入具有最高 优先级的分组之中。它们的优先级顺序 是：ingroup，defgroup，addtogroup， weakgroup。weakgroup 类似一个低优先级的 addtogroup。在.h 文件中可以使用 高优先级的命令定义层次结构，在.c 文件中\weakgroup 就不需要准确遵循.h 文 件中定义的层次结构。
Baidu Nhomakorabea
JavaDoc 风格，中间的"*"号可选。 /** * 注释 */ Qt 风格，中间的"*"号可选。 /*! * 注释 */ C++风格的变体，或者最后一个"/"改为"！"也可以。 /// 单行注释 /// 注释 /// 更加显著的表示。 /////////////////////////////////////////// /// 注释 /////////////////////////////////////////// 简要描述亦有多种表示方式。 在上述注释块中使用\brief 命令，详细注释在空行之后开始。 /*! \brief 简要描述 * 继续 * * 详细注释 */ JAVADOC_AUTOBRIEF 设置为 YES 后，在 JavaDoc 风格的注释中，第一个点号之前 的内容被自动设置为简要描述。 对于多行 C++变体，这个选项亦会起到相同的作用。 /** 简要描述.详细描述 * 注释 */ C++变体风格。 /// 简要描述 /* 详细描述 */
命名空间等可以分布在多个分组中，而成员实体（member）如变量、函数、typedef 等只能归属于一个分组。
定义分组的方法是在特殊注释块中使用命令\defgroup 和\addtogroup。 defgroup 的格式如下：
\defgroup <唯一标识名> （中间可以有空格的标题）
两次使用同一标识名，在 doxygen 解析的时候会出现错误。命令 addtogroup 与 defgroup 不同的地方在于，如果使用了同一标识，则会在改组中加入新的项， 如果标识不重复，则会创建分组。addtogroup 中的标题是可选的。