Win7下Doxygen配置与使用

1.  下载与安装

1.1 下载

Doxygen官方安装程序及其手册下载地址，目前使用版本为1.8.8。

安装程序：http://www.stack.nl/~dimitri/doxygen/download.html

图 1-1 Doxygen安装程序下载界面

在线帮助：http://www.stack.nl/~dimitri/doxygen/manual

图 1-2 Doxygen帮助文档下载界面

GraphViz Doxygen官方安装下载地址及其在线帮助地址，目前使用版本为2.38。

安装程序：http://www.graphviz.org/pub/graphviz/stable/windows/

图 1-3 GraphViz安装程序下载界面

在线帮助：http://www.graphviz.org/Documentation.php

图 1-4 GraphViz在线帮助界面

1.2 安装

以上两个安装程序可以任意安装，但是一定要记住Graphviz的安装路径，Doxygen的设置中要使用此路径以生成调用关系图。

2.  Doxygen配置与使用

2.1 基础配置

Doxygen的配置向导可以完成项目路径、工作模式、输出文档、图片工具四个方面的简要配置。

在图2-1中展示了项目路径配置的相关内容：其一，可以设置项目的名称、概述、版本号和项目标志；其二，可以设置源代码所在路径，递归扫描指是否将子文件夹加入源码搜索路径；其三，可以设置代码文档的输出路径，html、rtf等不同格式的代码文档以相应的文件夹存储在此路径之下。

图 2-1 项目配置

在图2-2所示的工作模式配置中，可以设定代码文档中的内容，即包括所有实体还是仅包括标记的实体。除此之外，还要手动选择Doxygen的运行时优化方案，这里选择了针对C语言和PHP的优化选项。

图 2-2 工作模式配置

在图2-3中，选择了输出HTML和RTF格式的代码文档，其中还可以设置HTML代码文档的输出内容，包括纯HTML文档、左侧带有导航树的HTML文档以及CHM文件支持，还可以更改HTML文档的配色方案。

图 2-3 输出代码文档设置

在图2-4所示的界面中，可以自由设置输出文档中是否含有图片、使用Doxygen内置图片工具生成图片、使用GraphViz生成图片三种方式。

图 2-4 图片工具设置

2.2 高级配置

高级配置是对基础配置的进一步细化，以形成不同风格的注释文档。由于涉及参数较多，本文并未给出所有参数的说明，这里仅介绍重要的参数，未尽部分还请读者自行阅读窗口左侧靠下的参数说明（详见图 25左侧红色矩形框所标识的区域）。

图2-5～图2-7完成了项目的详细配置，请注意输出语言一定要选择Chinese，一定要勾选图2-6中的JAVADOC_AUTOBRIEF选项和图2-7中的MARKDOWN_SUPPORT、AUTOLINK_SUPPORT选项，依次表示支持JavaDoc风格注释、Markdown标记方法、注释实体自动链接三种功能。

图 2-5 项目配置一

图 2-6 项目配置二

图 2-7 项目配置三

图2-8中则展示了Doxygen运行时所抽取的内容，一般采用默认设置，也可结合需求根据参数说明自行修改。

图 2-8 代码文档中包含的内容

在图2-9中，用户可以自定义Doxygen的运行日志所显示的内容与方式，可以通过运行日志检查注释的正误。

图 2-9 Doxygen运行日志的显示内容和格式

图2-10和图2-11依次说明了源码搜索路径、示例代码搜索路径和外部图片搜索路径的设置，这里一定要注意源码的编码格式设置为GBK。一旦文件编码格式有误，代码文档中就会出现乱码。

图 2-10 输入设置一——源码路径与编码格式

图 2-11 输入设置二——示例代码和图片的搜索设置

可以通过图2-12实现代码文档与源文件之间的交叉引用，方便阅读，一般使用默认设置。

图 212 源码与文档交叉引用设置

利用图2-13中索引方法设置，可以实现代码文档中的各注释对象的出现顺序，即按照字母顺序或者先后顺序显示。

图 2-13 索引方法设置

图2-14和图2-15分别展示了HTML文档、CHM文档的设置方法，其中CHM文档的生成需要HHC编译器，一般的路径为C:\Program Files\HTML Help Workshop。

图 2-14 HTML文档设置

图 2-15 CHM文档设置

代码的RTF文档设置如图图2-16，如果是小型项目最好勾选COMPACT_RTF选项，据说可以使得文档更紧凑。如果选中RTF_HYPERLINKS选项，则在RTF文档中会以链接的形式显示注释的对象。另外，如果RTF文档中的页码不能正常显示，请使用WORD中的更新域的命令更新文档即可。

图 2-16 RTF文档设置

通过图2-17所示的界面，在选择了GraphViz的路径之后，可以设置GraphViz生成图片的种类。

图 2-17 GraphViz的图片选项和路径设置

至此，已经完成Doxygen的所有设置，可以利用【File】和【Settings】菜单保存现有设置、导入已有配置等功能。

2.3 运行Doxygen

Doxygen的运行界面如图2-18所示，可以在该界面生成代码文档、显示结果和配置文件、保存日志等功能。

图 2-18 Doxygen的运行界面

请注意，如果Doxygen的运行窗口出现错误或者警告，请仔细阅读并找出问题所在，修改注释后即可。

另外，再次申明：如果RTF文档中不能正确显示页码，请对整篇文档使用"更新域"操作。