Doxygen 使用说明

Doxygen  简介

Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。


Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。
　　对于未归档的源文件，也可以通过配置Doxygen来提取代码结构。或者借助自动生成的包含依赖图（includedependency graphs）、继承图（inheritance diagram）以及协作图（collaborationdiagram）来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。
　　一个好的程序设计师，在写程序时，都会在适当的地方加上合适的批注。如果，能够在撰写批注时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的文件。这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。
　　Doxygen 就是这样的一个工具。在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文件了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文件。

安装, 下载 自己在网上找找怎么搞,不过在我国的局域网上访问不了它的主页的,您可以委托国外的朋友帮您下载,然后给您传回来.

下来 我就给大家介绍一下这个东西倒底是怎么个使用法:
它的功能大概就是: 把代码上的注解 生成一个html 或者 chm 或者 pdf 等 文档
哇,哪还等什么赶紧把我的代码生成一个文档吧…. 等等.. 其实它还没那么智能…


您必须按它的规范写注释,才能生成文档哦.. 真tmd的麻烦..
我首先给大家说说它常用的一些注解规范吧. 其实再深一点我也不懂-_-!
它大概 格式就是@后面有个关键字 这个关键字 说明了你的注解是什么. 参数啊. 返回值啊….

头文件模板:
/** @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
///< 在这里写你要加的东西

eg:
HINSTANCE m_hRes; ///< 要使用的资源句柄
CString  _strWndName; ///< 目标接收消息的窗口名称

5.2.2   常用指令介绍
@file 档案的批注说明。
@author 作者的信息
@brief 用于class 或function的简易说明 eg：@brief 本函数负责打印错误信息串
@param 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return 描述该函数的返回值情况eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval 描述返回值类型 eg: @retval NULL 空字符串。@retval !NULL 非空字符串。
@note 注解
@attention 注意
@warning 警告信息
@enum 引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum
@var 引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey
@class 引用某个类，格式：@class <name> [<header-file>] [<header-name>] eg:@class CTest "inc/class.h"
@exception 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo 对将要做的事情进行注释
@see 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since 通常用来说明从什么版本、时间写此部分代码。
@code  在注释中开始说明一段代码，直到@endcode命令。
@endcode  在注释中代码段的结束。
@pre 用来说明代码项的前提条件。
@post 用来说明代码项之后的使用条件。
@deprecated 这个函数可能会在将来的版本中取消。
@defgroup 模块名
@class 声明一个类 
@fn 声明一个函数



关于DoxyGen 软件使用值得注意的几点:
使用的中文情况下:

首先设置你的要生成的项目目录:
Wizard->Project-> Source code directory -> Select

在Expert->Project->OUTPUT_LANGUAG 中选择chinese

在Expert->Input->INPUT_ENCODING 中填写GB2312

如果你要显示Private 变量的注解
在Expert->Build->EXTRACT_PRIVATE 中勾选

输出
Wizard->Output 如果选择.chm 将没有搜索功能

其它选项默认