Mike的分享空间
Doxygen的注释规则
date: 2015.05.04; modification:2015.05.04
目录:
1 注释模板
1.1 头文件模板:
/** @brief 摘要
* @file 文件名
* @author 作者
* @version 版本号
* @date 你啥时候搞的
* @note 注解
* @since 自从
*/
1.2 函数的注释:
/** 这里写这个函数是干什么用的
@param i1[in] 输入参数1
@param i2[in] 输入参数2
@param o3[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 //这个函数可能在以后的版本中取消 所谓的什么过时列表
1.3 行注释模板
变量或者只有一行注解的东东,不超过一行的注释:
/**< 在这里写你要加的东西 */
OR
///< 在这里写你要加的东西
2 常用关键字列表
@author 作者的信息
@brief 用于class 或function的简易说明 eg:@brief 本函数负责打印错误信息串
@bug 被标记的代码会在Bug列表中出现
@class 类名
@date 日期
@file 文件名,可以默认为空,DoxyGen会自己加
@param 主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明
@return 描述该函数的返回值情况eg: @return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE
@retval 描述返回值类型 eg: @retval NULL 空字符串。@retval !NULL 非空字符串。
@note 注解
@attention 注意
@name 分组名
@warning 警告信息
@enum 引用了某个枚举,Doxygen会在该枚举处产生一个链接 eg:@enum CTest::MyEnum
@var 引用了某个变量,Doxygen会在该枚举处产生一个链接 eg:@var CTest::m_FileKey
@class 引用某个类,格式:@class [] [] eg:@class CTest "inc/class.h"
@exception 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
@todo 对将要做的事情进行注释
@see see also字段
@relates 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since 从哪个版本后开始有这个函数的
@code 在注释中开始说明一段代码,直到@endcode命令。
@endcode 在注释中代码段的结束。
@remarks 备注
@pre 用来说明代码项的前提条件。
@post 用来说明代码项之后的使用条件。
@deprecated 这个函数可能会在将来的版本中取消。
@defgroup 模块名
@{ 模块开始
@} 模块结束
@class 声明一个类
@version 版本号
@fn 声明一个函数
@par 开始一个段落,段落名称描述由你自己指定,比如可以写一段示例代码
- 一级项目符号
-# 二级项目符号
3 参考
http://blog.csdn.net/wangxvfeng101/article/details/7301115
Human knowledge belongs to the world
Contact: wytabc@126.com
声明: 本站如有侵权行为请及时通知至以上邮箱