C + + annotation specification

C + + annotation specification

Doxygen is an open-source, cross-platform, document system that is described in a similar Javadoc style, fully supported in C, C + +, Java, objective-c, and IDL languages, partially supported by PHP, C #. In view of Doxygen's good annotation style, it is based on Doxygen to form its own annotation specification.

1. General Statement of annotations

-------------------------------------------------------------------//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) >>/-------------------------------------------------------------------//Date and time at compile time//------------------------------------ -------------------------------#define Ost_timestamp __date__ "" __time__

    2. Document header  

/****************************************************************************** OpenST Basic Tool Library                                                                            * * Copyright (C) Henry.wen [email protected] * *                                                 * * 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 has received a copy of the G NU general public License * * along with OST.               If not, see 

3. Namespaces

/** * @brief 命名空间的简单概述 \n(换行) * 命名空间的详细概述 */namespace OST { }

4. Classes, structs, enumeration callouts

/** * @brief 类的简单概述 \n(换行) * 类的详细概述 */class Example { };

Enum type definition, struct type definition annotation style similar

/** * @brief 简要说明文字 */typedef struct 结构体名字 { 成员1, /*!< 简要说明文字 */ or ///<说明， /**<说明 */ 成员2, /*!< 简要说明文字 */ or ///<说明， /**<说明 */ 成员3, /*!< 简要说明文字 */ or ///<说明， /**<说明 */ }结构体别名;

5. Function Annotation Principle

/** * @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);

Note: Specify function notes or important annotation instruction operators note format as follows: @note brief description   retval: Specifies the function return value description instruction operator. (Note: The previous return is a bit different.) The retval format is as follows: @retval return value brief description   PRE: Specifies the function precondition directive operator pre format as follows: @pre brief description   par: Specifying extensibility instructions Operator speaking. (it is generally used with code, Endcode) the par format is as follows: @par extension name   code, Endcode: Specify code, Endcode format as follows: @code brief description (content) @endcode   See: Specify the Information. The see format is as follows: @see brief reference   Deprecated: Specifies the function obsolete instruction operator. The deprecated format is as follows: @deprecated A brief description of the bug explained by the Debug bug description, @bug warning Description (warning) defines something that must be known about the function, @warning Note description (remarks) Define some note information about this function, @remarks the work to be done (TODO) to show what will be done in the near future, @todo use the example description (example) example, @example example.cpp

/*** @brief 打开文件 \n* 文件打开成功后，必须使用::CloseFile函数关闭* @param[in] fileName 文件名* @param[in] fileMode 文件模式，可以由以下几个模块组合而成：* -r读取* -w 可写* -a 添加* -t 文本模式(不能与b联用)* -b 二进制模式(不能与t联用)* @return 返回文件编号* --1表示打开文件失败(生成时:.-1)* @note文件打开成功后，必须使用::CloseFile函数关闭* @par 示例:* @code* //用文本只读方式打开文件* int ret = OpenFile("test.txt", "a");* @endcode* @see 函数::ReadFile::CloseFile (“::”是指定有连接功能,可以看文档里的CloseFile变成绿,点击它可以跳转到CloseFile.)* @deprecated由于特殊的原因，这个函数可能会在将来的版本中取消*/int OpenFile(const char* fileName, const char* fileMode);/*** @brief 关闭文件* @param [in] file 文件** @retval 0 成功* @retval -1 失败* @pre file 必须使用OpenFile的返回值*/ int CloseFile(int file);

-: Generate a Black heart circle. -#: Specifies sequential tagging. ::: Specifies the connection function function. (Note: The Space and ":" have connectivity, but it is recommended to use "::". Useful only for functions. They are in the following format: (-and:: example is in front, just introduction-#例子. )-Brief description of-#:: Examples of functions:

/*** @param [in] person 只能输入以下参数：* -# a:代表张三 // 生成 1. a:代表张三* -# b:代表李四 // 生成 2. b:代表李四* -# c:代表王二 // 生成 3. c:代表王二*/void GetPerson(int p);

6. Variable annotations

/// 简述/** 详细描述. */

Or

//! 简述//! 详细描述//! 从这里开始int m_variable_1; ///< 成员变量m_variable_1说明int m_variable_2; ///< 成员变量m_variable_1说明 /*** @brief 成员变量m_c简要说明** 成员变量m_variable_3的详细说明，这里可以对变量进行* 详细的说明和描述，具体方法和函数的标注是一样的*/bool m_variable_3;

If the variable needs to be described in detail can be written in accordance with M_varibale_3, note that m_variable_2 and m_variable_3 must be blank line between, otherwise it will cause the summary of m_variable_2 disappear 7. Module Callout Module Definition format:

/*** @defgroup 模块名 页的标题名 (模块名只能英文,这个可以随便取.在一个源文件里不能相同)* @{ (跟c语言{一样起作用域功能)*/… 定义的内容 …/** @} */

Cases:

/*** @defgroup HenryWen Example.cpp* @{*/ … 定义的内容 …/** @} */

8. Grouping label grouping definition format:

/*** @name 分组说明文字* @{*/… 定义的内容 …/** @} */

Cases:

/*** @name PI常量* @{*/#define PI 3.1415926737/** @} *//*** @name 数组固定长度常量* @{*/const int g_ARRAY_MAX = 1024;/** @} */

C + + annotation specification