确立 注释规范

 由于采用的是文档生成doxygen工具，所以制定的注释如下（不断完善中）：

 

文件头注释：

/**

-----------------------------------------------------------------------------

brief 简短描述

author 作者列表

date 日期

Copyright (c) 2009 Foxery Organization

-----------------------------------------------------------------------------

*/

 

类注释：

/**

* @class

* @brief 简洁的类说明

*

* 较为详细的类说明

* ......

*/

 

函数注释：

/**

* @brief 简洁的函数说明

*

* 较详细的函数说明

*

* @param arg1 第一个参数的说明

* @param arg2 第二个参数的说明

* @param arg3 第三个参数的说明

* @return 返回值的说明

* ......

*/

 

简短注释：

/// 这是一个xxxx

/**@brief 简洁的注释*/

 

 

doxygen标识参数功能综述：

@param   参数名及其解释（我还习惯在param后加[IN]表示输入还是输出参数）

@exception 用来说明异常类及抛出条件

@return   对函数返回值做解释

@note   表示注解，暴露给源码阅读者的文档

@remark   表示评论，暴露给客户程序员的文档

@since   表示从那个版本起开始有了这个函数

@deprecated 引起不推荐使用的警告

@see   表示交叉参考

 

 

 

 

性能警告注释：

//<<< 性能 >>>

/* 这里填写说明

*  一行不够写第二行

*/

 

 

 

移植性警告注释：

//<<< 移植 >>>

/* 这里填写说明

*  一行不够写第二行

*/