参考文章
块注释建议统一使用
/** * comment */行注释建议统一使用
///...comment... /** …… */项目注释块用于对项目进行描述,每个项目只出现一次,一般可以放在main.c主函数文件头部。对于其它类型的项目,置于定义项目入口函数的文件中。对于无入口函数的项目,比如静态库项目,置于较关键且不会被外部项目引用的文件中。
项目注释块以“/** @mainpage”开头,以“*/”结束。包含项目描述、及功能描述、用法描述、注意事项4个描述章节。
项目描述章节描述项目名称、作者、代码库目录、项目详细描述4项内容,建议采用HTML的表格语法进行对齐描述。
功能描述章节列举该项目的主要功能。
用法描述章节列举该项目的主要使用方法,主要针对动态库、静态库等会被其它项目使用的项目。对于其它类型的项目,该章节可省略。
注意事项章节描述该项目的注意事项、依赖项目等相关信息。
要善于使用表格及一些标号语句
/** @mainpage 智能井盖固件程序 * <table> * <tr><th>Project <td>ble_app_smc * <tr><th>Author <td>wanghuan * <tr><th>Source <td>E:\keil_workspace\NORDIC\nRF52832_htwh_sdk15.0\examples\ble_peripheral\ble_app_smc_freertos-doxygen * </table> * @section 项目详细描述 * 通过智能井盖管理系统的部署,管理人员通过手机APP与管理平台就能对辖区内井盖的安装、开闭、状态进行管理,出现异常情况及时通知维护人员进行检修,保障排水正常,保障市民安全。 * * @section 功能描述 * -# 本工程基于蓝牙新品nRF52832开发 * -# 本工程基于蓝牙协议栈开发,协议栈版本 SDK-15.0 * -# 智能井盖采用NB-IoT模组为ME3616 * * @section 用法描述 * -# 智能井盖检测器安装指导 * -# 智能井盖检测器使用前需配置使能 * * @section 固件更新 * <table> * <tr><th>Date <th>H_Version <th>S_Version <th>Author <th>Description </tr> * <tr><td>2018/08/17 <td>1.0 <td>S02010041808171 <td>wanghuan <td>创建初始版本 </tr> * <tr><td>2019/06/24 <td>1.3 <td>S02010041906241 <td>wanghuan <td> * -# 电信平台增加上报需应答,应答超时时间默认40s;\n * 代码宏:ME3616_NOTIFY_NEED_RPLY_EN * -# 新增PSM进入超时处理,默认超时处理模组关机,超时时间默认200s;\n * 代码宏:ME3616_PSM_TIMEOUT_HANDLE_EN * -# 信号强度获取接口函数修改,增加可靠性,详见 me3616_getSignal(); * -# 调试指令新增周期上报测试指令,710A-0D * </tr> * </table> ********************************************************************************** */文件注释块对源代码文件进行注释,包括头文件(.h)、C++文件(.cpp)或C文件(*.c)。文件注释块置于对应文件的开头,至少包括文件名(@file)、文件简要说明(@brief)、作者(@author)、创建日期(@date)和版本号(@version)5个标记。如下所示:
/** @file main.c * @brief 项目主函数文件 * @details 主要包含协议应用栈程序框架,main函数入口 * @author wanghuan any question please send mail to 371463817@qq.com * @date 2018-8-17 * @version V1.0 * @copyright Copyright (c) 2018-2020 江苏亨通光网科技有限公司 ********************************************************************************** * @attention * 硬件平台:nRF52832_QFAA \n * SDK版本:nRF5_SDK_15.0.0 * @par 修改日志: * <table> * <tr><th>Date <th>Version <th>Author <th>Description * <tr><td>2018/08/17 <td>1.0 <td>wanghuan <td>创建初始版本 * </table> * ********************************************************************************** */该注释块对函数进行描述,位于对应函数的定义上方。
函数注释块包含以下内容:
简要说明标记(@brief),内容为方法或函数的简要说明。 详细描述,详细描述与@brief标记之间空一行”\n”或者使用@details。 若干个参数描述标记(@param),数量与该方法的输入参数个数相同。格式为:“@param 参数名称 参数说明”。 返回值标记(@return),描述该方法的返回值,格式为:“@return 返回值类型 返回值描述”。若返回值为void类型,则省略该标记。 返回值说明(@retval),对具体返回值进行描述说明。 特殊标记-:生成一个黑心圆. -#:指定按顺序标记。 :::指定连接函数功能。(注:空格和“:”有连接功能,但建议还是使用”::”。只对函数有用。)
以下是一个函数注释块实例,实际根据情况增减
/** @brief NB模组向云平台上报数据 * @param[in] handle NB模组驱动句柄 * @param[in] *data 上报数据指针 * @param[in] len 上报数据长度 * @param[in] rcc_enabled 上报时是否主动释放RCC链接 * @param[in] update_enabled 上报时是否更新注册(只适用于onenet) * @param[in] report_fail_try_type 上报失败重新注册类型 \n * @ref NB_REPFAIL_REG_TRY 出错立即重试 \n * @ref NB_REPFAIL_REG_DELAY_TRY 出错延缓重试,在延迟期间如果正常则重新延缓,适用于高频率上报(上报失败重新注册超时15min) \n * @ref NB_REPFAIL_REG_NO_TRY 出错不重试 * @return 函数执行结果 * - NB_NOTIFY_SUCCESS 上报成功 * - NB_NOTIFY_FAIL 上报失败 * - NB_IOT_REGIST_FAILED 注册失败返回 * - Others 其他错误 * @par 示例: * @code * 移动平台发送数据 AT+MIPLNOTIFY=0,122553,3308,0,5900,4,4,50,0,0 * 电信平台发送数据 AT+M2MCLISEND=000101 * @endcode * @see :: ME3616_FxnTable */模块注释用于将一系列相关功能的函数、枚举、结构等归入一个模块并进行描述。模块注释块包括模块起始注释块及模块结束注释块两个部分。
模块起始注释块包含模块名称标记(@defgroup)、模块简介标记(@brief)、模块详细描述及模块起始标记(@{)4个部份。
模块结束注释用于结束一模块描述定义,格式为“/** @} */”。与模块起始注释块成对出现。包含在模块起始注释块与结束注释块之间的所有内容将归入该模块。
若需要将其它文件中定义的内容归入一个已定义的模块,可使用简略的模块起始注释块与结束注释块括起需要归入该模块的内容。简略的模块起始注释块仅包含相同的模块名称标记(@defgroup)。
如下所示:
/** @defgroup bsp_me3616 Bsp me3616 driver module. * @{ * @ingroup bsp_drivers * @brief 使用该驱动之前,先进行驱动句柄的实例注册. \n * ME3616驱动支持云平台Onenet和OceanConnect \n * 当使能GPS驱动使能时,支持GPS操作 */ /** @} bsp_me3616*/自定义命名的一组内容注释
/** @name 协议栈用全局参数 * @brief 蓝牙5协议栈参数配置(广播、连接、安全等)相关宏定义,协议栈各模块句柄等全局参数 * @{ */ /** @} 协议栈用全局参数 */