doxygen使用

Doxygen介绍：

Doxygen 是一个 C++, C, Java, Objective-C、Python、IDL (CORBA 和 Microsoft flavors)、Fortran、VHDL、PHP、C#和D语言的文档生成器。可以运行在大多数类Unix系统，以及Mac OS X操作系统和Microsoft Windows 。 初始版本的Doxygen借鉴了一些老版本DOC++的代码；随后，Doxygen源代码由Dimitri van Heesch重写。

Doxygen是一个编写软件参考文档的工具。 该文档是直接写在代码中，因此比较容易保持更新。 Doxygen 可以交叉引用文档和代码，使文件的读者可以很容易地引用实际的代码。

要想使用Doxygen，需要三大步骤

1.Doxygen及其相关内容下载

1.1Doxygen下载

      由于国内墙了Doxygen的官网，但sourceforge还是可以使用

进行下载

本文使用的为Doxygen 1.8.3.1

安装，我们将在配置的时候使用doxywizard，Doxygen的GUI版本。

1.2HTML Help Workshop下载

如果你希望你的Doxygen自动生成chm，那么请下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll

进行下载

下载其中的htmlhelp.exe并安装，记住安装目录，我们将在Doxygen配置时使用。

1.3 Graphviz

Graphviz在Doxygen用于自动生成类图的工具。

登陆官网发现被墙了，只能在天朝大局域网内随便找个方便的连接了。

安装并记录安装目录，同样我们一会需要配置Doxygen

2.配置Doxygen

2.1基本配置

在基本配置中，会介绍一些关于Doxygen的基本配置，例如各种乱码，输出内容等。

首先我们打开开始-》所有程序-》Doxygen-》doxywizard

在开始之前，打开Doxygen GUI frontend的File，保存到你需要做测试的目录

会出现一个Doxyfile的配置文件，修改选项后保存，下次通过Doxygen打开这个文件可以还原该项目的配置

第一步，选择你的工作目录（源代码位置），点击Select。

第二步，进行配置

首先修改Project name，选择扫描源代码的目录，Source code directory：，勾选Scan recursively

之后选择输出目录，作为测试选择桌面进行查看。

在Wizard的Topics下的Mode，选择All Entities，可以输出相对完整的功能，是否包含源代码看你自身情况，在下面选择好你的语言。这里作者使用的是C所以选择C or PHP

在Output中，如果你需要输出chm格式，请勾选。

在Diagrams中选择使用GraphViz包，来输出UML。

2.2字符集乱码

Expert中，你需要首选确定你所输出的语言，个人使用中文

在Expert的Input中，很重要的是INPUT_ENCODING项，如果你使用的为微软默认字符集请填写GBK，不然目录乱码。

在Expert的HTML中，首先要看HHC_LOCATION选项，添加安装目录（注：作者目录为D:/build/doxygen/hcc/HTML Help Workshop/hhc.exe）

勾选CHM_INDEX_ENCODING，在你源代码中的字符集是什么就填写什么，作者的C由于使用keil，所以填写为GBK，java对eclipse切换了字符集所以为UTF-8，还有注意给chm命名以方便寻找。

2.3GraphViz的输出

在Expert的Build中，选择要输出的配置项，如果不清楚可以参考下面图片

之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK

为了减少chm体积，在DOT_IMAGE_FORMAT中选择gif或者jpg，均可。

最后选择好DOT_PATH所输出的位置。

配置GraphViz 暂缺

2.4生成文档

之后点击Run-》Run doxygen。

这时你可以看到一个没有任何注释与说明的关系图。（chm请在html文件内寻找）

3.关于注释格式

由于Doxygen支持 javadoc的格式，但还有部分区别，按照如下方式可以作为注释的模板，可以参考Doxygen的具体文档，形成你自己的风格。
1.文件注释：
/**************************************************************************/
 /** 
* @brief 对于文件的简单注释 
* @details 对于文件的详细注释 
* @addtogroup example 范例 
* @author Alex.shi 
* @version 0.01 
* @date 2010/05/25 
****************************************************************************** 
* Copyright (c), 2010, Alex Co., Ltd. 
****************************************************************************** 
* Edit History /n 
* -------------------------------------------------------------------------/n 
* DATE NAME DESCRIPTION /n 
* 2010/05/25 Alex.shi Create./n 
****************************************************************************** 
* @{ 
*****************************************************************************/ 
……………… // 源码内容 
 
……………… // 源码内容 
 
 /** @}***********************************************************/ 

2.函数注释：

/**
* 设置日期的显存
* @param[in] beginPos 对应区域开始显示的地址
* @param[in] order order>0: year/month/date;order=0: date/month/year
* @param[in] linkChar 日期间的连接符, 目前仅支持 '*''#''-''_''='
* @param[in] year 1-9999
* @param[in] month 1-12
* @param[in] day 1-31
* @return 操作结果, 见 ERR_LED_E
* @note 只有在调用 LED_Update 后才起效
* @see ::LED_Update ::LED_SetSerialBuf ::LED_SetCharBuf 
* @see ::LED_SetTimeBuf ::LED_SetMoneyBuf ::LED_ClearAreaBuf
*/ 
 
PUBLIC ERR_LED_E LED_SetDateBuf(uint8 beginPos, uint8 order, uint8 linkChar,
uint16 year, uint8 month, uint8 day)

说明：

@param：注释输入/输出参数；

@return：返回值

@see：参考内容，若 LED_Update() 函数存在的话，将会在文档中显示为 LED_Update的链接。

@note：显示注意事项

3.普通注释

/** 区域类型 */
 typedef enum
{
LED_AREA_NULL = 0, /**< 区域头 */ 
LED_AREA_SERIAL_NO, /**< 序号区域 */ 
LED_AREA_TEXT, /**< 文本区域 */ 
LED_AREA_TIME, /**< 时间区域 */ 
LED_AREA_MONEY, /**< 金额区域 */ 
LED_AREA_UNDEFINE /**< 区域尾 */ 
}LED_AREA_E;
说明：
/** 注释内容 */ ：对该注释后面的内容（如枚举类型、变量等）进行注释；
/**< 区域头 */ ：对该注释前面的内容（如枚举类型、变量等）进行注释；

4. 块定义
块定义主要是将相关的一些变量、函数等信息统一在一起显示，并给他们取个名字。如底下的例子，将程序涉及到的几种图标用宏定义出来，并放在一起，起名为“各种图标定义”。
/****************************************************************/
 /**
* @name 各种图标定义
* @{
*/  
 /** 锁图标 */ 
#define LED_ICON_LOCK 0x0001 
 /** 日图标 */ 
#define LED_ICON_DAY 0x0002
 /** 月图标 */ 
#define LED_ICON_MONTH 0x0004
 ……  
/** @}各种图标定义**************************************************/ 

结尾：

注意保存Doxygen的配置文件，下次使用打开该配置即可，Doxygen虽然说明了如何使用，但是作者开始并没进行保存，很多调整的配置项丢失。