目录
Doxygen注释格式
块注释
建议统一使用
/**
*……
*/
行注释建议统一使用
///…
/** …… */
由于Doxygen 对于批注是视为在解释后面的程序代码。(以上默认在解释后面的程序)
例如:
/**
* @brief Override function Plan in parent class Planner.
* @param planning_init_point
* @param frame Current planning framework. (track node)
* @param reference_line_info 。
* @return OK if planning succeeds; error otherwise.
*/
apollo::common::Status PlanOnReferenceLine(
const common::TrajectoryPoint& planning_init_point, Frame* frame,
ReferenceLineInfo* reference_line_info) override;
针对一些常用的指令做说明:
@file | 档案的批注说明。 |
@author | 作者的信息 |
@brief | 用于class 或function的批注中,后面为class 或function的简易说明。 |
@param | 格式为 @param arg_name 参数说明 主要用于函式说明中,后面接参数的名字,然后再接关于该参数的说明。 |
@return | 后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。 |
@retval | 格式为 @retval value 传回值说明 主要用于函式说明中,说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。 |
如果要批注前面的程序代码则需用下面格式的批注符号。
/*!< ... 批注 ... */
/**< ... 批注 ... */ (推荐)
//!< ... 批注 ...
///< ... 批注 ... (推荐)
例如:
using apollo::common::ErrorCode; ///<错误码
using apollo::common::Status; ///<状态
2. 文件注释
文件注释通常放在整个文件开头。
/**
* @file 文件名
* @brief 简介
* @details 细节
* @mainpage 工程概览
* @author 作者
* @email 邮箱
* @version 版本号
* @date 年-月-日
* @license 版权
*/
例如:
/**
* @file Test.h
* @brief 测试头文件
* @details 这个是测试Doxygen
* @mainpage 工程概览
* @author jdzhangxin
* @email jdzhangxin@126.com
* @version 1.0.0
* @date 2017-11-17
*/
生成文档效果
3. 类定义注释
类定义的注释方式非常简单,使用@brief
后面填写类的概述,换行填写类的详细信息。
/**
* @brief 类的简单概述
* 类的详细概述
*/
例如:
/**
* @brief 测试类
* 主要用来演示Doxygen类的注释方式
*/
class Test{
};
生成文档效果
命名空间、结构体、联合体、枚举定义与类定义注释方式一致。
4. 常量/变量的注释
常量/变量包括以下几种类型
- 全局常量变量
- 宏定义
- 类/结构体/联合体的成员变量
- 枚举类型的成员
注释分为两种方式,可根据具体情况自行选择
- 代码前注释
例如:/// 注释 常量/变量
/// 缓存大小 #define BUFSIZ 1024*4
- 代码后注释
例如:常量/变量 ///< 注释
生成文档效果#define BUFSIZ 1024*4 ///< 缓存大小
5. 函数注释
-
简约注释
函数注释主要包含函数简介(@brief
)、参数说明('@param')、返回说明(@return
)和返回值说明(@retval
)四部分。/** * @brief 函数简介 * * @param 形参 参数说明 * @param 形参 参数说明 * @return 返回说明 * @retval 返回值说明 */
-
详细注释
可以根据需要添加详细说明(@detail
)、注解(@note
)、注意(@attention
)、警告(@warning
)或者异常(@exception
)等。/** * @brief 函数简介 * @detail 详细说明 * * @param 形参 参数说明 * @param 形参 参数说明 * @return 返回说明 * @retval 返回值说明 * @note 注解 * @attention 注意 * @warning 警告 * @exception 异常 */
-
例子
以main()
函数为例添加函数注释。/** * @brief 主函数 * @details 程序唯一入口 * * @param argc 命令参数个数 * @param argv 命令参数指针数组 * @return 程序执行成功与否 * @retval 0 程序执行成功 * @retval 1 程序执行失败 * @note 这里只是一个简单的例子 */ int main(int argc, char* argv[])
生成文档效果
其他
下面一些标注方式可以根据需要选择使用。
命令 | 生成字段名 | 说明 |
---|---|---|
@see | 参考 | |
@class | 引用类 | 用于文档生成连接 |
@var | 引用变量 | 用于文档生成连接 |
@enum | 引用枚举 | 用于文档生成连接 |
@code | 代码块开始 | 与@endcode 成对使用 |
@endcode | 代码块结束 | 与@code 成对使用 |
@bug | 缺陷 | 链接到所有缺陷汇总的缺陷列表 |
@todo | TODO | 链接到所有TODO 汇总的TODO 列表 |
@example | 使用例子说明 | |
@remarks | 备注说明 | |
@pre | 函数前置条件 | |
@deprecated | 函数过时说明 |
按照类型来注释
1)文件注释
/**
* @file CommonType.h
* @brief 常见类型定义
* @author Vincent
* @date 2015-5-24
* @version A001
* @copyright Vincent
*/
2)函数注释
/**
* 读取文件
* @param[in] fileNameLen 文件名长度
* @param[in] fileName 文件名
* @param[in] dataLen 数据长度
* @param[out] fileData 输出数据
* @return 0,执行成功,非0,失败,详见
* @ref RetCode.h
* @see
* @note
*/
UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData);
3)类型/宏定义注释
/**
* 2字节字符类型
*/
typedef unsigned short WORD;
4)枚举/结构注释
/** 枚举类型*/
enum COLOR{
RED=0, ///< 红色
GREEN=1,///< 绿色
YELLOW=2///< 黄色
};
希望对你有帮助。