背景

这一块的内容更多的是作为了解,但是可以以这样的规范作为自己的编程注释习惯,提高自己的软实力。

Doxygen注释语法

注释格式

块注释建议统一使用

/**

……

***/

行注释建议统一使用

///< …

/** …… */

Doxygen常用注释命令

@exception <exception-object> {exception description} 对一个异常对象进行注释。

@warning {warning message } 一些需要注意的事情

@todo { things to be done } 对将要做的事情进行注释,链接到所有TODO 汇总的TODO 列表

@bug 缺陷,链接到所有缺陷汇总的缺陷列表

@see {comment with reference to other items } 一段包含其他部分引用的注释,中间包含对其他代码项的名称,自动产生对其的引用链接。

@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。

@since {text} 通常用来说明从什么版本、时间写此部分代码。

@deprecated

@pre { description of the precondition } 用来说明代码项的前提条件。

@post { description of the postcondition } 用来说明代码项之后的使用条件。

@code 在注释中开始说明一段代码,直到@endcode命令。

@endcode 注释中代码段的结束。

@code .. @endcode 包含一段代码

@addtogroup 添加到一个组。

@brief 概要信息

@deprecated 已废弃函数

@details  详细描述

@note 开始一个段落,用来描述一些注意事项

@par 开始一个段落,段落名称描述由你自己指定

@param 标记一个参数的意义

@fn 函数说明

@ingroup 加入到一个组

@return 描述返回意义

@retval 描述返回值意义

@include 包含文件

@var、@enum、@struct、@class 对变量、美剧、结构体、类等进行标注

Doxygen注释示例

1.项目注释

项目注释块用于对项目进行描述,每个项目只出现一次,一般可以放在main.c主函数文件头部。对于其它类型的项目,置于定义项目入口函数的文件中。对于无入口函数的项目,比如静态库项目,置于较关键且不会被外部项目引用的文件中。

项目注释块以/** @mainpage开头,以*/结束。包含项目描述、及功能描述、用法描述、注意事项4个描述章节。

项目描述章节描述项目名称、作者、代码库目录、项目详细描述4项内容,建议采用HTML的表格语法进行对齐描述。

功能描述章节列举该项目的主要功能。

用法描述章节列举该项目的主要使用方法,主要针对动态库、静态库等会被其它项目使用的项目。对于其它类型的项目,该章节可省略。

注意事项章节描述该项目的注意事项、依赖项目等相关信息。

要善于使用表格及一些标号语句

例如

/**@mainpage  春节12响固件程序
* <table>
* <tr><th>Project <td>dozen_bangs
* <tr><th>Author <td>李长条
* <tr><th>Source <td>D:\workspace\demo_project\examples\dozen_bangs\dozen_bangs-doxygen
* </table>
* @section 项目详细描述
* 不让地球继续流浪。
*
* @section 功能描述
* -# 破坏
*
* @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>
* -# 无
* </tr>
* </table>
**********************************************************************************
*/

2.文件注释

文件注释块对源代码文件进行注释,包括头文件(.h)、C++文件(.cpp)或C文件(*.c)。文件注释块置于对应文件的开头,至少包括文件名(@file)、文件简要说明(@brief)、作者(@author)、创建日期(@date)和版本号(@version)5个标记。如下所示:

/**@file  main.c
* @brief 项目主函数文件
* @details 主要包含协议应用栈程序框架,main函数入口
* @author 李长条
* @date 2018-8-17
* @version V1.0
* @copyright Copyright (c) 2050
**********************************************************************************
* @attention
* SDK版本:v2050.0.0
* @par 修改日志:
* <table>
* <tr><th>Date <th>Version <th>Author <th>Description
* <tr><td>2010/02/17 <td>1.0 <td>wanghuan <td>创建初始版本
* </table>
*
**********************************************************************************
*/

3.函数注释

该注释块对函数进行描述,位于对应函数的定义上方。

函数注释块包含以下内容:

  • 简要说明标记(@brief),内容为方法 / 函数的简要说明。
  • 详细描述,详细描述与@brief标记之间空一行”\n”或者使用@details。
  • 若干个参数描述标记(@param),数量与该方法的输入参数个数相同。格式为:“@param 参数名称 参数说明”。
  • 返回值标记(@return),描述该方法的返回值,格式为:“@return 返回值类型 返回值描述”。若返回值为void类型,则省略该标记。
  • 返回值说明(@retval),对具体返回值进行描述说明。
  • 特殊标记

-:生成一个黑心圆.

-#:指定按顺序标记。

:::指定连接函数功能。(注:空格和“:”有连接功能,但建议还是使用”::”。只对函数有用。)

以下是一个函数注释块实例,实际根据情况增减:

/**@brief 注册函数
* @param[in] *data 上报数据指针
* @param[in] len 上报数据长度
* @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
* int ret = register_all(&data, len, RT_TYPE_T1)
* @endcode
* @see :: xx表
*/

4. 枚举、结构体等注释

/**@enum msg_types
* @brief 定义驱动上报应用消息类型
*/
/**@struct info
* @brief 信息结构体 \n
* 定义存储的信息
*/
typedef struct 结构体名字
{
成员1, ///< 简要说明文字 */ 如果不加<,则会认为是成员2的注释
成员2, ///< 简要说明文字
成员3, ///< 简要说明文字
}结构体别名;

5.模块注释

模块注释用于将一系列相关功能的函数、枚举、结构等归入一个模块并进行描述。模块注释块包括模块起始注释块及模块结束注释块两个部分。

模块起始注释块包含模块名称标记(@defgroup)、模块简介标记(@brief)、模块详细描述及模块起始标记(@{)4个部份。

模块结束注释用于结束一模块描述定义,格式为/** @} */。与模块起始注释块成对出现。包含在模块起始注释块与结束注释块之间的所有内容将归入该模块。

若需要将其它文件中定义的内容归入一个已定义的模块,可使用简略的模块起始注释块与结束注释块括起需要归入该模块的内容。简略的模块起始注释块仅包含相同的模块名称标记(@defgroup)。

如下所示:

/**@defgroup bsp_me3616 Bsp me3616 driver module.
* @{
* @ingroup bsp_drivers
* @brief 使用该驱动之前,先进行驱动句柄的实例注册. \n
* ME3616驱动支持云平台Onenet和OceanConnect \n
* 当使能GPS驱动使能时,支持GPS操作
*/ /** @} bsp_me3616*/

5.分组注释

自定义命名的一组内容注释

/**@name 协议栈用全局参数
* @brief 协议栈参数配置(广播、连接、安全等)相关宏定义,协议栈各模块句柄等全局参数
* @{
*/ /** @} 协议栈用全局参数 */

Doxygen 注释语法规范的更多相关文章

  1. JSLint检测Javascript语法规范

    前端javascript代码编写中,有一个不错的工具叫JSLint,可以检查代码规范化,压缩JS,CSS等,但是他的语法规范检查个人觉得太“苛刻”了,会提示各种各样的问题修改建议,有时候提示的信息我们 ...

  2. C++注释和doxygen注释

    C++注释 C++的注释只有两种: 单行注释,以“//”开头: 段落注释,以“/*”开始,以“*/”结束. int value; // value是一个整型变量,这是一句单行注释 /* Test是一个 ...

  3. web前端(14)—— JavaScript的数据类型,语法规范1

    编辑器选择 对js的编辑器选用,有很多,能对html编辑的,也能对js编辑,比如notepad++,visual studio code,webstom,atom,pycharm,sublime te ...

  4. JavaScript 中语法规范及调试

    JavaScript 中语法规范及调试 版权声明:未经博主授权,内容严禁分享转载 JavaScript 开发环境 JavaScript 脚本可以使用任意一款纯文本编辑器进行编程开发. 常见的前端开发编 ...

  5. 前端学习 -- Xhtml语法规范

    Xhtml语法规范 HTML中不区分大小写,但是尽量使用小写: HTML的注释不能嵌套: 标签必须结构完整{要么成对出现,要么自结束标签,虽然浏览器会帮我们修正一些不符合规范的内容} 标签可以嵌套但是 ...

  6. 语法规范:BNF与ABNF 巴斯克范式

    语法规范:BNF与ABNF 巴斯克范式 BNF  巴科斯范式(BNF: Backus-Naur Form 的缩写)是由 John Backus 和 Peter Naur 首先引入的用来描述计算机语言语 ...

  7. XHTML语法规范

    <head> <meta charset="utf-8" /> <title>xhtml语法规范</title> </head ...

  8. HTML&CSS基础-xHtml语法规范

    HTML&CSS基础-xHtml语法规范 作者:尹正杰 版权声明:原创作品,谢绝转载!否则将追究法律责任. 一.html源码 <!DOCTYPE html> <html> ...

  9. [19/06/04-星期二] HTML基础_实体(转义字符)、图片标签(img)、元标签(meta)、语法规范、内联框架(iframe)、超链接

    一.实体(转义字符) 在HTML中,一些诸如<.> 就是普通的小于号和大于号不能直接使用,因为浏览可能会把它当成一个标签去解析,所以需要一些特殊字符去表示这些特殊字符, 这些字符我们称他们 ...

随机推荐

  1. 关于找不到指定的模块,异常来自HRESULT:0x8007007E的解决方法

    上午从公司前辈那里拷贝到的ASP.NET代码,在自己机器上部署的时候发现问题,直接报错,找不到指定的模块,异常来自HRESULT:0x8007007E.并且一大堆警告. 在网上百度很多解决方法,归纳如 ...

  2. Verilog状态机

    以1011为例 代码如下: //1011(Meay型) module state1(clk,in,rst_n,out); input clk; input rst_n; input in; outpu ...

  3. 第七届蓝桥杯javaB组真题解析-四平方和(第八题)

    题目 /* 四平方和 四平方和定理,又称为拉格朗日定理: 每个正整数都可以表示为至多4个正整数的平方和. 如果把0包括进去,就正好可以表示为4个数的平方和. 比如: 5 = 0^2 + 0^2 + 1 ...

  4. AI基础概念

    基础概念 epoch:使用训练的全部数据对模型进行一次完整的训练,被成为“一代训练”.当一个完整的数据集通过了神经网络一次并且返回了一次,这个过程称为一次epoch.(也就是说,所有训练样本在神经网络 ...

  5. js中的arguments、Array.prototype.slice.call()

    类数组对象:arguments js把传入到这个函数的全部参数存储在arguments里面,其实arguments也是个对象,而且是一个特殊的对象,它的属性名是按照传入参数的序列来的,第1个参数的属性 ...

  6. C++ class without pointer members

      写在前面 Object Oriented class 的分类:带指针的class和不带指针的class, class 的声明         这里有一个inline的概念,写在类里面的默认为inl ...

  7. Go语言中的数组与数组切片

    Go中的数组与C的数组一样,只是定义方法不同 c: int a[10][10] Go [10][10]int 定义并初始化 array1 := [5]int{1,2,3,4,5} 变量名 := [in ...

  8. 一个基础又很重要的知识点:JDBC原理(基本案例和面试知识点)

    JDBC全称又叫做Java DataBase Connectivity,就是Java数据库连接,说白了就是用Java语言来操作数据库.这篇文章主要是对JDBC的原理进行讲解.不会专注于其使用.主要是理 ...

  9. 用python发送qq邮件

    一.需要开启smtp服务,获取授权密码. 在qq邮箱的设置里开启smtp 二.代码 # -*- coding:utf-8 -*- import smtplib from email.mime.text ...

  10. vh搭配vw进行响应式布局

    1.浏览器兼容性: IE8-不支持,IOS7.1-不支持,android4.3-不支持 2. vh代表浏览器视口高度(100vh等于当前浏览器的整个高度) 3.vw代表浏览器视口的宽度 (100vw等 ...