1.标注总述
//-------------------------------------------------------------------
// Platform Defines
//-------------------------------------------------------------------
enum
{
OST_PLATFORM_WIN32 = 1,
OST_PLATFORM_LINUX_X86 = 2,
OST_PLATFORM_LINUX_ARM = 3,
OST_PLATFORM_ANDROID = 4,
OST_PLATFORM_MACOSX = 5,
};
//-------------------------------------------------------------------
// API Export/Import Macros
//-------------------------------------------------------------------
/** Indicates an exported and imported shared library function. */
#define OST_API_EXPORT __declspec(dllexport)
#define OST_API_IMPORT __declspec(dllimport)
//-------------------------------------------------------------------
// Digital Image Macros
//-------------------------------------------------------------------
#define OST_PI 3.141592653589793f
#define OST_RGB2GRAY(r, g, b) ( ((b) * 117 + (g) * 601 + (r) * 306) >> 10 )
//-------------------------------------------------------------------
// date and time at compile time
//-------------------------------------------------------------------
#define OST_TIMESTAMP __DATE__ " " __TIME__
2. 文件头的标注
/*****************************************************************************
* OpenST Basic tool library *
* Copyright (C) 2014 Henry.Wen renhuabest@163.com. *
* *
* This file is part of OST. *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License version 3 as *
* published by the Free Software Foundation. *
* *
* You should have received a copy of the GNU General Public License *
* along with OST. If not, see <http://www.gnu.org/licenses/>. *
* *
* Unless required by applicable law or agreed to in writing, software *
* distributed under the License is distributed on an "AS IS" BASIS, *
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
* See the License for the specific language governing permissions and *
* limitations under the License. *
* *
* @file Example.h *
* @brief 对文件的简述 *
* Details. *
* *
* @author Henry.Wen *
* @email renhuabest@163.com *
* @version 1.0.0.1(版本号) *
* @date renhuabest@163.com *
* @license GNU General Public License (GPL) *
* *
*----------------------------------------------------------------------------*
* Remark : Description *
*----------------------------------------------------------------------------*
* Change History : *
* <Date> | <Version> | <Author> | <Description> *
*----------------------------------------------------------------------------*
* 2014/01/24 | 1.0.0.1 | Henry.Wen | Create file *
*----------------------------------------------------------------------------*
* *
*****************************************************************************/
3.命名空间
/**
* @brief 命名空间的简单概述 \n(换行)
* 命名空间的详细概述
*/
namespace OST
{
}
4. 类、结构、枚举标注
/**
* @brief 类的简单概述 \n(换行)
* 类的详细概述
*/
class Example
{
};
枚举类型定义、结构体类型定义注释风格类似
/**
* @brief 简要说明文字
*/
typedef struct 结构体名字
{
成员1, /*!< 简要说明文字 */ or ///<说明, /**<说明 */
成员2, /*!< 简要说明文字 */ or ///<说明, /**<说明 */
成员3, /*!< 简要说明文字 */ or ///<说明, /**<说明 */
}结构体别名;
5. 函数注释原则
/**
* @brief 函数简要说明-测试函数
* @param index 参数1
* @param t 参数2 @see CTest
*
* @return 返回说明
* -<em>false</em> fail
* -<em>true</em> succeed
*/
bool Test(int index, const CTest& t);
6. 变量注释
/// 简述
/** 详细描述. */
或者
//! 简述
//! 详细描述
//! 从这里开始
int m_variable_1; ///< 成员变量m_variable_1说明
int m_variable_2; ///< 成员变量m_variable_1说明
/**
* @brief 成员变量m_c简要说明
*
* 成员变量m_variable_3的详细说明,这里可以对变量进行
* 详细的说明和描述,具体方法和函数的标注是一样的
*/
bool m_variable_3;
如果变量需要详细说明的可已按照m_varibale_3的写法写,注意,m_variable_2和m_variable_3之间一定需要空行,否则会导致m_variable_2的简述消失
7. 模块标注 模块定义格式
/**
* @defgroup 模块名 页的标题名 (模块名只能英文,这个可以随便取.在一个源文件里不能相同)
* @{ (跟c语言{一样起作用域功能)
*/
… 定义的内容 …
/** @} */
例:
/**
* @defgroup HenryWen Example.cpp
* @{
*/
… 定义的内容 …
/** @} */
8. 分组标注 分组定义格式
/**
* @name 分组说明文字
* @{
*/
… 定义的内容 …
/** @} */
例:
/**
* @name PI常量
* @{
*/
#define PI 3.1415926737
/** @} */
/**
* @name 数组固定长度常量
* @{
*/
const int g_ARRAY_MAX = 1024;
/** @} */