Doxygen生成注释文档

概述：

 Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。

工具的准备 

本人已经下载了这三个软件，打包后放在：点击打开链接

 

Doxygen下载

 

下载地址：http://www.onlinedown.net/soft/117010.htm

htmlhelp下载

如果你希望你的Doxygen自动生成chm，那么请下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll。 下载地址：  http://msdn.microsoft.com/en-us/library/ms669985.aspx

Graphviz的下载

 

graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。

下载地址：http://www.skycn.com/soft/appid/6971.html

Doxygen工具的配置

在安装好开始配置Doxygen工具，运行Doxywizard。会出现以下界面

 

配置工作目录

 

点击Select选择自己的Doxygen的安装目录

 

 

 

配置Wizard选项卡

配置Project

 

首先修改Project name，选择扫描源代码的目录，Source code directory：，勾选Scan recursively  （递归扫描），之后选择输出目录。

 

 

 

配置Model

 

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

 

 

 

配置Output

 

 

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

 

 

 

配置Diagrams

 

 

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

 

 

 

配置expert选项卡

配置project

 

 

说明：编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312.

TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。

 

 

 

配置Build

 

 

Build页面，这个页面是生成帮助信息中比较关键的配置页面：

EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。

EXTRACT_PRIVATE 表示：输出private函数。

EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。

SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列

表。

INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显

示。

 

 

 

配置Input

 

 

说明：INPUT_ENCODING (输入的源文件的编码)，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

总结：我查看到我的代码文件是utf-8的（vs2013中打开文件 选另存为可看到编码格式）（（VS2012的话）：文件->高级保存选项)。

 

 

 

配置HTML

 

 

在Expert的HTML中，首先要看HHC_LOCATION选项，添加安装目录（注：作者目录为C:/Program Files (x86)/HTML Help Workshop/hhc.exe）

勾选CHM_INDEX_ENCODING，在你源代码中的字符集是什么就填写什么，

 

 

 

配置dot

 

 

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

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

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

 

 

 

Run选项卡

 

点击点击 Run doxygen 按钮， Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。

 

 

 

 

 

注释规范

以下是想使用doxygen工具生成程序文档需要在代码中遵守的注释规范(不全)：

头文件模板:

/** @brief 这里写你的摘要
 *  @file 你的文件名
 *  @author 谁tmd的搞的
 *  @version 版本了
 *  @date  你啥时候搞的
 *  @note       注解. 例如: 本文件有什么具体功能啊,使用时要注意什么啊…..
 *  @since    自从  例如: 自从2012年地球爆炸后这个文件就从地球上消失了…..
 */

几句费话:
 美中不足的是它没有修改历史记录. 我只能用@since来暂时代替它了.
 除开始和结尾 中间 @前的*不是必须的,这里只是为了美观.

函数的注释:

/**  这里写这个函数是干什么用的
 @param[in]  输入参数1
 @param[in]  输入参数2
 @param[out]  输出参数1
 @return    返回值解释一下
 @warning 警告: 例如: 参数不能为空啊,内存要外部释放之类的费话
 @note 注解  随便你了
 @see                相当于是请参考xxoo函数之类的
*/

费话:
这些东西并不是固定的你要哪几个就写哪几个.


关于返回值也可以这样搞
@retval 1 成功
@retval 0 失败


有时我们可能会写段示例代码在注释中这样搞:
在你的注释中加入这样的代码
@par 示例:
@code
extern  IThread *pThread;
HANDLE hEvent = pThread->GetEventHandle();
while(WaitForSingleObject(hEvent,0) != WAIT_OBJECT_0)
{
//Do something
}
@endcode


还有几个你可能用上的东东:
@todo       //我觉得这个描述算法比较好
@exception   // 这个应该是用来说明你这个函数会抛出什么异常
@deprecated  //这个函数可能在以后的版本中取消 所谓的什么过时列表


eg:
/**  构造函数 
 @param[in]  pConfig 指向 TASKCONFIG 结构体的指针
 @param[in]  strWndName 目标窗口的名称, 如果此参数为空则不和任何窗口交互
 @param[in]  hRes 欲使用的资源句柄,如果参数为空则不使用资源
 @warning    pConfig 不能为空 
 @note     申请 pConfig 内存
 @see     IThread
*/
CThread_Plug(TASKCONFIG *pConfig,LPCTSTR strWndName,HINSTANCE hRes);


变量或者只有一行注解的东东,不超过一行的注释:
 /**< 在这里写你要加的东西 */
OR
///< 在这里写你要加的东西


参考资料：

     1、Doxygen配置以及注释详细说明文档：doxygen_manual-1.8.9.1.pdf

　　2、C++ 程序文档生成器介绍(doxygen)

　　3、使用doxygen生成chm范例

　　4、嵌入式C语言中的Doxygen注释模板

　　5、Doxygen使用简介

      6、Doxygen给C程序生成注释文档