Doxygen 注释语法和使用
目录
Doxygen注释格式
块注释
2. 文件注释
3. 类定义注释
4. 常量/变量的注释
5. 函数注释
其他
按照类型来注释
1)文件注释
2)函数注释
3)类型/宏定义注释
4)枚举/结构注释
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///< 黄色
};
希望对你有帮助。
Doxygen 注释语法和使用相关推荐
- doxygen 注释规范_编程规范 - doxygen注释规范示例(C++)
doxygen注释规范示例(C++) doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写. ...
- 使用VA助手如何快速添加注释(按doxygen注释规范)
原文首发于微信公众号「3D视觉工坊」:使用VA助手如何快速添加注释(按doxygen注释规范) 首先,关于VA助手的破解安装教程,请参考:VS2015 Visual Assist X 破解版安装教程 ...
- c++ doxygen 注释规范_C语言代码注释参考
简述 该参考是基于Doxygen注释规范进行简单归纳,可以适当根据自己的需求进行约定. Doxygen可以从一套归档源文件开始,生成HTML格式的在线类浏览器,或离线的LATEX.RTF参考手册.简单 ...
- doxygen注释规范示例(C++)
doxygen注释规范示例(C++) doxygen能根据code的注释自动生成code的帮助文档,并且doxygen是一个跨平台的开源的软件,但是要生成帮助文档,code内的注释必须按一定规则书写. ...
- c++ doxygen 注释规范_利用Doxygen给C程序生成注释文档
利用Doxygen为C程序生成注释文档 一.Doxygen工具的安装 利用Doxygen工具生成API帮助文档需要下载安装以下三个软件: (1)Doxygen:可以从一套归档源文件开始,生成HTML格 ...
- Qt中使用Doxygen注释生成总结
为了团队快速的将项目中的注释生成一个注释文档,相比传统的一个个类,函数以及关键点添加注释来说,使用工具可以生成多种样式以及标准的说明文档. 1.在qt中使用Doxygen注释标准来注释 我的qtcre ...
- pycharm注释语法
1. 单行注释 语法格式: #[空格]说明性文字信息 注:可放一行代码的后面进行说明 添加快捷键: Ctrl+/ 取消快捷键: 同上 也可同时选中多行按下快捷键 2. 多行注释 语法格式: " ...
- c代码Doxygen注释规范
c代码Doxygen注释规范 前言:良好得注释风格利于后期维护和团队协作开发,使得代码逻辑清晰,意图明了.Doxygen是一种能自动提取代码内注释生成版主文档的开源软件,它是跨平台的.非开源项目也许并 ...
- Qt:ini文件注释语法
ini文件注释语法,#后面为注释内容 m_setting = new QSettings(CONFIG_FILE, QSettings::IniFormat); m_setting->setVa ...
最新文章
- leetcode - 1191. K 次串联后最大子数组之和
- neo4j 返回 return
- 水泵调速c语言实验程序,C语言实验最原始.doc
- 吴恩达神经网络和深度学习-学习笔记-16-超参数的系统的调整方法
- ocs添加仓库受限问题
- 联想台式机usb驱动_windows安装系列教程—驱动安装
- webrtc在ubuntu14.04上的编译过程(12.04亦可)
- nsga2 matlab,NSGA2算法特征选择MATLAB实现(多目标)
- 3d max2012 安装加破解
- VMware虚拟机的使用和克隆
- 直接在云端服务器里面修改代码,深夜折腾:实现云端服务器代码与Git库同步
- 什么是附近推?附近推怎么投放?
- OpenCV + CPP 系列(卅三)图像特征提取(Harris角点检测、Shi-Tomasi角点检测、自定义角点检测)
- uip1.0核心模块uip_process函数解读
- maven 一次打包多个maven项目
- 苹果更新协议-税务协议
- jsp页面使用webcam,获取照片
- setting文件配置
- postgre数据库 例如oracle的nvl()函数
- 初创企业如何选购企业邮箱?
热门文章
- python-识别验证码
- ug转速进给计算机使用方法,UG程序模块和自动加载转速进给刀具库参数教程
- 在高并发、高负载的情况下,如何给表添加字段并设置DEFAULT值?
- erlang 中#(井号)号的作用
- 【文献阅读】Sensor Fusion Algorithm Design in Detecting Vehicles Using Laser Scanner and Stereo Vision
- 张江高科技园区企业_知名品牌入驻张江高科技园区 共筑上海浦东新高度
- sql object_id() 对应oracle,关于ORACLE通过file_id与block_id定位数据库对象遇到的问题引发的思考...
- js获取svg中g元素的宽高
- 龙猫Java自学-SpringMVC
- 抖音SEO矩阵系统如何运营?如何开发?