doxygen代码文档生成工具的使用
Doxygen使用讲解及注释格式
1Doxygen简介
Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc 兼容。Doxygen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。
Doxygen 是一个程序的文档产生工具，可将程序中的特定注释转换成为说明文档。通常我们在写程序时，或多或少都会写上注释，但是对于其它人而言，要直接探索程序里的注释，与打捞铁达尼号同样的辛苦。大部分有用的注释都是针对函数，类别等等的说明。所以，如果能依据程序本身的结构，将注释经过处理重新整理成为一个纯粹的参考手册，对于后面利用或维护这份程序代码的人而言将会减少许多的负担。对于未归档的源文件，也可以通过配置Doxygen 来提取代码结构。或者借助自动生成的包含依赖图（includedependency graphs）、继承图（inheritance diagram）以及协作图（collaborationdiagram）来可视化文档之间的关系。
一个好的程序设计师，在写程序时，都会在适当的地方加上合适的注释。如果，能够在撰写注释时，稍微符合某种格式，接着就可以通过一个工具依据程序结构及注释产生出漂亮的文档，这将令程序设计师从繁重的文档编写工作中解脱出来。Doxygen 就是这样的一个工具。在写注释时，按照它所制订的一些规则编写，接着就可以产生出漂亮的文件了。因此，Doxygen 的使用可分为两大部分，首先是特定格式的注释撰写，第二便是利用Doxygen 的工具来产生文档。本文将对Doxygen 的常用功能做一个入门介绍，更多功能或完整支持请参考Doxygen的用户手册。
2目的
本文档旨在介绍doxygen的使用及统一代码注释，编写出符合doxygen要求的良好的代码注释风格，并可以利用doxygen生成代码文档，提高后续维护人员维护代码的难度，并提高代码的可读性。
本文档为基于《郑州云涌嵌入式程序规范第一版.doc》，不涉及变量命名、缩进等要求，仅涉及注释部分的格式，指出统一风格的Doxygen可识别的注释格式，作为其补充和修订。
3安装
3.1Doxygen安装
这里只介绍Windows 二进制安装，后面所有的介绍都是基于Windows 平台。可以去http://www.doxygen.nl/download.html 页面获取最新版本。截至本文档写作时的最新版本是1.8.10，本文档的写作也是基于Doxygen 1.8.10。Doxygen 的Windows 二进制包是自动安装文件，只需按照对话框提示即可。
3.2 graphviz安装
graphviz是一个生成图形化函数调用关系的工具，双击附件中的“2014-01-16_graphviz-2.37.20140115.msi”的文件进行安装。
3.3 HTML helper安装
解压HHWorkShop474.rar文件，双击里面的exe进行安装
4运行第一个示例
首先我们通过运行一个现成的简单示例来熟悉 Doxygen 的操作流程。
假设所需的文件包括源码都在目录“ F://doxygen”下面，跟着下面的步骤为文件“ lpc17xx_rtc.c”生成文档。
4.1 打开图形向导Doxywizard
打开Doxygen 的图形前端Doxywizard，这是一个向导程序，界面如图 3.1所示。
3.2 选择配置文件
选择菜单“ file/open...”打开浏览配置文件对话框，浏览文件夹“ doxygen”并选择文件“ D oxyfile”，单击按钮“打开”即可。
3.3 生成文档
单击标签页“ run”，再单击该标签页下的按钮“ Run doxygen”，此时可以在该标签页下的日志窗口中看到 Doxygen 的运行输出信息。
稍等片刻，日志窗口停止输出信息，并在最后一行显示“ *** Doxygen has finished”字样就表示文档已经顺利生成。
默认生成的是 HTML 格式的网页文档，可以看到文件夹“ doxygen”下多出了一个目录“html”，默认的主页文件为“ index.html”
3.4 浏览文档
文档生成后单击标签页“ run”左下角的按钮“ Show HTML output”就可以用系统默认的浏览器打开生成的文档，如图 3.2所示。
如果使用的是低版本 IE 浏览器，在显示上可能会有些问题，原因是低版本的 IE 浏览器对 HTML 标准支持的不是很好，建议使用 mozilla firefox、 google chrome 或
Apple Safari 等对 HTML 标准支持比较好的浏览器。
4单模块简单示例
通过图 3.2可以看到， Doxygen生成的文档十分漂亮，赏心悦目。如何使我们的代码能通过 Doxygen 自动生成漂亮文档呢？其实很简单，在编写代码注释时按照 Doxygen 的规矩来就行了，注释即文档，后文中很多地方提及的注释都可以理解成文档。现以文件“ lpc17xx_rtc.c”为例介绍为代码编写可文档化的注释，生成的文档的效果如图 3.2所示。
4.1 编写注释
如何编写Doxygen风格注释呢？现以文件“ lpc17xx_rtc.c”为例进行简要说明，文件内容如程序清单 4.1所示。
程序清单 4.1 简单注释示例
/* Peripheral group ----------------------------------------------------------- */
/** @defgroup RTC 实时时钟
* 实时时钟模块，包含了对rtc的操作接口函数。
* @{
*/
/*********************************************************************//** * @ingroup RTC
* @brief Start/Stop RTC peripheral
* @details
* @param[in] RTCx R TC peripheral selected, should be LPC_RTC
* @param[in] NewState New State of this function, should be:
* - ENABLE: The time counters are enabled
* - DISABLE: The time counters are disabled
* @return None
**********************************************************************/ void RTC_Cmd (LPC_RTC_TypeDef *RTCx, FunctionalState NewState)
{
CHECK_PARAM(PARAM_RTCx(RTCx));
CHECK_PARAM(PARAM_FUNCTIONALSTATE(NewState));
if (NewState == ENABLE)
{
RTCx->CCR |= RTC_CCR_CLKEN;
}
else
{
RTCx->CCR &= (~RTC_CCR_CLKEN) & RTC_CCR_BITMASK;
}
}
/**
可以看到程序清单 4.1中的注释比我们通常写的代码注释多了些以“ @”开头的标记，正是这些标记告诉Doxygen如何提取文档以及如何组织文档结构的。下面对这段注释进行解释。
4.1.1 有效注释
“ /**”表示要求 Doxygen 处理这段注释，否则如果写成“ /*”或“ /****”
之类这段注释就会被忽略掉。这样就可以控制哪些注释要出现在文档中供用户阅读，哪些注释仅仅是给代码编写者或维护者阅读。
4.1.2 定义模块
第 2 行的“ @def group”表示定义一个模块，语法是“ @defgroup 模块id 模块名”。则
“ @defgroup RTC 实时时钟”定义了一个名为“实时时钟”的模块。模块id为“RTC”模块 ID 必须使用英文，这个 ID 的作用是区分不同模块，并可供其他模块或注释引用。下面一行是对“ RTC”模块的说明。
4.1.3 加入到模块
第 7 行“ @ingroup RTC”表示把这个注释块加入到模块“RTC”中。
4.1.4 函数注释
“ @brief”是一个简要描述，让阅读者快速了解这个函数的功能。
“ @details”是详细描述，这个可以省略。
“@param”开始描述函数的参数，格式为“ @param 参数名参数描述”。
“ @ret urn”对返回值进行描述，格式为“ @ret urn 返回值返回值描述”。
“ @note”是注意事项。
4.2 生成配置
编写完代码注释后，在使用 Doxygen 为代码生成文档前还需要为工程生成一个配置文件。跟着下面的步骤进行设置，未加说明的配置请留空（使用默认配置）。
4.2.1 项目配置
打开Doxygen 的图形前端Doxywizard，选择“ Wizard”标签页，然后选择“ Topics”栏下的“ Project”项，进入项目设置界面，如图 4.1所示。
1. 选择项目路径
单击“ Select...”，浏览并选择“ F://doxygen”作为当前工作路径。
2. 设置项目名称
在“ Project name:”后面填项目名，如“ My project”。
在“ Project synopsis:”后面填项目简介，如“ lpc1768 rtc driver”。
在“ Project version or id:”后面填项目版本号，如“ V1.0”。
3. 设置源码路径
单击“ Source code directory:”后面的按钮“ Select...”选择源码路径，如选择“Doxygen”。
4.2.2 模式配置
选择“ Wizard”标签页，然后选择“ Topics”栏下的“ Mode”项，进入模式设置界
面，如图 4.2所示。
选中“ Documented entities only”和“ Optimize for C or PHP output”。选择“ Wizard”标签页，然后选择“ Topics”栏下的“ Output”项，进入输出设置界面，
如图 4.3所示。
单击expert选项卡找到html这一项。如下图进行设置。
其中CHM_FILE用来指定生成的chm程序文档的文件名，HHC_LOCATION用来指定生成chm 格式文档的工具的路径，此处填写安装HTML helper的路径，指定到文件hhc.exe.
4.2.4 图表配置
选择“ Wizard”标签页，然后选择“ Topics”栏下的“ Diagrams”项，进入图表设
置界面，选择“ Use dot tool from graphviz package”。
装步骤中GraphViz的安装目录下的bin目录，如下图。
4.2.5 支持中文
经过前面的配置 Doxygen 已经可以生成英文的文档了，要支持输出中文还需要做一些额外的配置。
1. 设置输出语言为中文
选择“ Expert”标签页进入专家设置界面，然后选择“ Topics”栏下的“ Project”
项，在右边窗口中找到“ OUTPUT_LANGUAGE”下拉框，单击选择“ Chinese”
2.设置输入编码
选择“ Expert”标签页，然后选择“ Topics”栏下的“ Input”项，在右边窗口中找到“ INPUT_ENCODING”，根据源码文件的编码格式进行设置。如源代码保存的是
“utf-8”编码，需要填写“utf-8”，否则当源码中有中文时，会出现乱码。
4.2.6 保存配置文件
至此配置已经完成，选择菜单“ File/Save”弹出保存文件对话框，选择当前工作目录，将文件命名为“ Doxygenfile”并保存。
4.3 生成文档并浏览
单击标签页“ run”，再单击该标签页下的按钮“ Run doxygen”，日志窗口将输出大量信息，等信息输出停止时文档就生成完毕。可以看到文件夹“ doxygen 快速入门”下多出了一个目录“ html”。
文档生成后单击标签页“ run”左下角的按钮“ Show HTML output”就可以用系统默认的浏览器打开生成的文档。也可以把目录“ html”下的文件“ index.html”拖到浏览器进行浏览。如果没有出现错误，会发现html目录下还有一个chm格式的文档。双击即可打开。
5 常用标记
5.1 几个常用标记
在编写程序时我们会把代码划分成不同的“模块”，这样代码层次结构清晰，便于阅读和理解。同样 Doxygen 也提供“模块化”的标记指令来把注释进行归类，生成“模块化”的文档。在前面的章节其实已经介绍了两个模块化指令： @defgroup 和@ingroup。为了便于对后面内容的理解，这里先介绍另外一个常用的模块化标记“ @addtogroup”，以及模块开始标记
“ @{”和结束标记“ @}”，还有一个用于结构体、枚举、联合体和类成员注释的标记
“ <”。
5.1.1 @addtogroup
“ @addtogroup”表示把注释加入到某个模块，语法为“ @addtogroup 模块标签”。这个和前面介绍过的“ @ingroup”很类似。
5.1.2 @{和@}
“ @{”和“ @}” 用于和“ @defgroup”、“ @addtogroup”以及“ @ingroup”组合来标记
1. /**
2. * @defgroup group_a 组 a 的名字
3. * 组 a 的详细描述
4. * @{
5. */
6. ......
7. /* @} */
8.
9. /**
10. * @addtogroup group_b
11. */
12. /* @{ */
13. ......
14. /* @} */
第 4 和 7 行之间的内容都属于模块“ group_a”，第 12 和 14 行之间的内容被加入到模块
“ group_b”。
注意第 4 行和第 12 行的细微区别，第 14 行另起了一行写“ @{”，这两种用法都是合法的，依个人习惯选用，不过第 4 行的写法更能体现“ @{”和“ @}”之间的内容属于“ group_a”。
5.1.3 成员注释
对于结构体、枚举、联合体和类，除了对整体注释外，多数情况对他们的成员也需要作出注释，这时使用标记“ <”跟在成员后面放置文档，如程序清单 5.2所示为成员注释示例。
第 1 行使用对常数宏放置文档，第 3 行对 my_struct 的成员 idx 放置文档，第 4 行对my_struct 的成员 buf 放置文档。
注意到成员注释可以使用“ /**<”或“ /*!<”，前者是 JavaDoc 风格，后者是 QT 风格，这个根据个人喜好使用，混合用也可以，不过为了代码风格统一，本文推荐 JavaDoc 风格。
程序清单 5.2 成员注释范例
1. #define BUF_SIZE 8 /**< buffer 大小 */
2. struct my_struct {
3. int idx; /**< buffer 索引 */
4. char buf[BUF_SIZE]; /*!< buffer 空间 */
5. };
参数注释“ @param”后紧跟“ [in]”表示输入参数，可以用“ [out]”表示输出参数，“ [in,out]”表示双向参数。
还可对参数的有效值使用“ @arg”进行了罗列，同时使用“ @b”指示参数用粗体显示。也可以使用‘-’来罗列。如代码清单
/*********************************************************************//**
* @brief Check whether if specified Location interrupt in
* RTC peripheral is set or not
* @param[in] RTCx RTC peripheral selected, should be LPC_RTC
* @param[in] IntType Interrupt location type, should be:
* - RTC_INT_COUNTER_INCREASE: Counter Increment Interrupt
* block generated an interrupt.
* - RTC_INT_ALARM: Alarm generated an
* interrupt.
* @return New state of specified Location interrupt in RTC peripheral
* (SET or RESET)
**********************************************************************/
IntStatus RTC_GetIntPending (LPC_RTC_TypeDef *RTCx, uint32_t IntType)
{
CHECK_PARAM(PARAM_RTCx(RTCx));
CHECK_PARAM(PARAM_RTC_INT(IntType));
return ((RTCx->ILR & IntType) ? SET : RESET);
}
效果如图：
一般使用“ @return”对返回值进行描述。也可以使用“ @retval”对返回值进行一一罗列。
5.2 文件标记
如代码清单所示，为常用文件标记。
/**********************************************************************
*//**
* @file lpc17xx_rtc.c
* @brief Contains all functions support for RTC firmware library on LPC17xx
* @version 3.1
* @date 6. June. 2011
* @author NXP MCU SW Application Team
*
* Copyright(C) 2011, NXP Semiconductor
* All rights reserved.
*
***********************************************************************
* Software that is described herein is for illustrative purposes only
* which provides customers with programming information regarding the
* products. This software is supplied "AS IS" without any warranties.
* NXP Semiconductors assumes no responsibility or liability for the
* use of the software, conveys no license or title under any patent,
* copyright, or mask work right to the product. NXP Semiconductors
* reserves the right to make changes in the software without
* notification. NXP Semiconductors also make no representation or
* warranty that such application will be suitable for the specified
* use without further testing or modification.
**********************************************************************/
效果如下图
6. 注释的书写建议
通过前面的介绍，对于 Doxygen 的使用和如何编写文档化注释有了一定的了解。Doxygen 能帮助我们生成格式漂亮的文档，但文档内容的质量还是靠程序员书写的注释来保证。
6.1 注释原则
注释应该怎么写，写多还是写少？过多的注释甚至会干扰对代码的阅读。
写注释的一个总的原则就是注释应该尽量用来表明作者的意图，至少也应该是对一部分代码的总结，而不应该是对代码的重复或者解释。对代码的重复或者解释的注释，看代码可
能更容易理解。
推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码
中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点：
(1) 避免对单独语句进行注释；
(2) 通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解
代码；
(3) 对读者可能会有疑问的地方进行注释；
(4) 对数据定义进行注释，而不是对其使用过程进行注释；
(5) 对于难于理解的代码，进行改写，而不要试图通过注释加以说明；4.3 小节。7. FAQ
1. 为什么在浏览器中看到很多乱码
可能源码文件中有 Doxygen 不能识别的编码，或者你的浏览器没有自动使用 UTF-8 编码进行编码显示。
2. 如何对生成文档进行更高级的控制
请参考 Doxygen 的用户手册，这些高级的控制不在本文的讨论范围内。
3. 如何把文档中页脚的版权声明替换成自己的
需要自行编写一个HTML文件做页脚，如程序清单 8.1所示为页脚HTML的内容形式，假设文件名为“ html_footer”。
选择 Doxygen 图形前端的“ Expert”标签页，在“ Topics”下选择“ HTML”项，在右边窗口中找到“ HTML_FOOTER”项，浏览选择“ html_footer”文件。
程序清单 8.1 定制 HTML 页脚示例
1.
2.
3. 本文档由 Doxygen $doxygenversion 于 $date 自动生成
4.