代码注释规范之Doxygen
1.Doxygen简介
Doxygen是一个程序的文档产生工具,可以将程序中的注释转换成说明文档或者说是API参考手册,从而减少程序员整理文档的时间。当然这里程序中的注释需要遵循一定的规则书写,才能让Doxygen识别和转化。
目前Doxygen可处理的程序语言包含C/C++、Java、Objective-C、IDL等,可产生出来的文档格式有HTML、XML、LaTeX、RTF等,此外还可衍生出不少其它格式,如HTML可以打包成CHM格式,而LaTeX可以通过一些工具产生出PS或是PDF文档等。
2.
2.Doxygen安装及使用
安装列表:
Doxygen: 下载地址,http://doxygen.nl/files/doxygen-1.8.15-setup.exe
HTML Help:微软官方用于生成HTML格式的help文件,下载地址,http://go.microsoft.com/fwlink/p/?linkid=14188
Graphviz:一种dot工具可以用来渲染出效果更好的图表,下载地址,https://graphviz.gitlab.io/_pages/Download/Download_windows.html
windows上安装很简单,无需特别设置。
2.1 Doxygen设置
1.向导
2.专家设置
2.1 Project
每个配置项均有详细鼠标放置时均有详细注释,以下是我的设置可供参考,特别注意语言,避免中文乱码
2.2 Build
EXTRACT_ALL 表示:输出所有的函数,但是private和static函数不属于其管制。
EXTRACT_PRIVATE 表示:输出private函数。
EXTRACT_STATIC 表示:输出static函数。同时还有几个EXTRACT,相应查看文档即可。
HIDE_UNDOC_MEMBERS表示:那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然,如果EXTRACT_ALL被启用,那么这个标志其实是被忽略的。
INTERNAL_DOCS 主要指:是否输出注解中的@internal部分。如果没有被启动,那么注解中所有的@internal部分都将在目标帮助中不可见。
CASE_SENSE_NAMES 表示:是否关注大小写名称,注意,如果开启了,那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说,建议永远不要开启。
HIDE_SCOPE_NAMES 表示:域隐藏,建议永远不要开启。
SHOW_INCLUDE_FILES 表示:是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列表。
INLINE_INFO :如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。
SORT_MEMBER_DOCS :如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显示。
GENERATE_TODOLIST :是否生成TODOLIST页面,如果开启,那么包含在@todo注解中的内容将会单独生成并显示在一个页面中,其他的GENERATE选项同。
SHOW_USED_FILES :是否在函数或类等的帮助中,最下面显示函数或类的来源文件。
SHOW_FILES :是否显示文件列表页面,如果开启,那么帮助中会存在一个一个文件列表索引页面。
2.3 input
2.4 Source Browser
2.5 HTML
2.6 Dot
3 Run 点击运行即可
生成文件在工程 /doc/html/ble_app_gnt.chm
效果如下:
3. Doxygen注释语法
3.1 注释格式
块注释建议统一使用
/**
……
*/
行注释建议统一使用
///< …
/** …… */
3.2 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 对变量、美剧、结构体、类等进行标注
3.3 Doxygen注释示例
3.3.1 项目注释
项目注释块用于对项目进行描述,每个项目只出现一次,一般可以放在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>
- **********************************************************************************
- */
3.3.2 文件注释
文件注释块对源代码文件进行注释,包括头文件(*.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>
- *
- **********************************************************************************
- */
3.3.3 函数注释
该注释块对函数进行描述,位于对应函数的定义上方。
函数注释块包含以下内容:
- 简要说明标记(@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
- */
3.3.4 枚举、结构体等注释
- /**@enum NB_msg_types_t
- * @brief 定义驱动上报应用消息类型
- */
- /**@struct ME3616_info_t
- * @brief ME3616信息结构体 \n
- * 定义存储ME3616的信息
- */
- typedef struct 结构体名字
- {
- 成员1, ///< 简要说明文字 */ 如果不加<,则会认为是成员2的注释
- 成员2, ///< 简要说明文字
- 成员3, ///< 简要说明文字
- }结构体别名;
3.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*/
3.3.5 分组注释
自定义命名的一组内容注释
- /**@name 协议栈用全局参数
- * @brief 蓝牙5协议栈参数配置(广播、连接、安全等)相关宏定义,协议栈各模块句柄等全局参数
- * @{
- */
- /** @} 协议栈用全局参数 */
代码注释规范之Doxygen的更多相关文章
- java代码注释规范
java代码注释规范 代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二 ...
- PHPDocument 代码注释规范总结
PHPDocument 代码注释规范 1. 安装phpDocumentor(不推荐命令行安装)在http://manual.phpdoc.org/下载最新版本的PhpDoc放在web服务器目录下使得通 ...
- [转]java代码注释规范
代码注释是架起程序设计者与程序阅读者之间的通信桥梁,最大限度的提高团队开发合作效率.也是程序代码可维护性的重要环节之一.所以我们不是为写注释而写注释.下面说一下我们在诉求网二期开发中使用的代码注释规范 ...
- 代码注释规范-IDEA 配置 Java 类方法注释模板
1. 引言 团队开发时,业务模块分配的越清晰,代码注释管理越完善,越有利于后面维护,后面再管理也方便不少.另外也起着"文字砖"的作用,你懂的.注释不需要很详细,把代码块方法 ...
- java开发规范总结_代码注释规范
规范需要平时编码过程中注意,是一个慢慢养成的好习惯 1.基本规则 1.注释应该使代码更加清晰易懂 2.注释要简单明了,只要提供能够明确理解程序所必要的信息就可以了.如果注释太复杂说明程序需要修改调 ...
- js/javascript代码注释规范与示例
文件注释 文件注释位于文件的最前面,应包括文件的以下信息:概要说明及版本(必须)项目地址(开源组件必须)版权声明(必须)开源协议(开源组件必须)版本号(必须)修改时间(必须),以ISO格式表示(可使用 ...
- [C++]项目中的代码注释规范(整理)
原文:http://blog.csdn.net/pleasecallmewhy/article/details/8658795 1 源文件头部注释 列出:版权.作者.编写日期和描述. 每行不要超过80 ...
- vs2008 多人同时开发项目时的代码注释规范格式 分类: C#小技巧 2014-04-23 14:12 297人阅读 评论(0) 收藏
多人同时开发一个项目,区分项目的那个窗体是谁开发的,例:下面的格式 /************************************************ 模块:服务器设置 ...
- PHPDocumentor代码注释规范说明
PHPDocumentor是一个的用PHP写的道具,对于有规则注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档. 标记 用途 描述 @abstract 抽象类的变量和方法 ...
随机推荐
- JAVA数组的基础入门>从零开始学java系列
目录 JAVA数组的基础入门 什么是数组,什么情况下使用数组 数组的创建方式 获取数组的数据 数组的内存模型 为什么数组查询修改快,而增删慢? 查询快的原因 增删慢的原因 数组的两种遍历方式以及区别 ...
- MarkDown语法(Typora软件为例)
Hello !我又来了 这篇文章主要给大家讲一下MarkDown的一些基础语法,MarkDown语法是一种轻量级标记语言,它允许人们使用易读易写的纯文本格式编写文档,然后转换成有效的XHTML( ...
- 三年Android开发快手、美团、支付宝连挂,怒刷1549页面试题字节上岸
刚开始面试的时候我真的是处处碰壁,面一家挂一家,面完之后怀疑自我,是不是自己真的太菜了找不到工作.工作本身就是双向选择,一家不行再换一家,总有合适的,千万不要因为别人的一句话就全盘否定自己,一定要自信 ...
- .Net Core如何优雅的实现中间件
在.Net Core的源码中,很多地方都有中间件的地方,Kestrel Server和Asp.net Core 等都用了中间件的设计,比如在Kestrel Server中,Http协议的1.0, 1. ...
- 深入理解jvm-2Edition-类文件结构
概述: 规范而独立的类文件结构以及只与类文件关联的虚拟机为Java实现了平台无关性,甚至还带来了一些语言无关性. 只要将源代码编译为Class文件规定的格式,JVM就可以执行. JVM的指令描述能力比 ...
- Java自定义注解使用和详解
前言 我们在做开发springboot 项目时候会遇到各种各样注解,使用各种各样注解,极大的简便了我们开发流程,方式,从JDK5开始支持 注解是Java语言的一种强大的功能 可以理解为代码上的特殊标记 ...
- ACM学习笔记:二叉堆
title : 堆 date : 2021-8-3 tags : ACM,数据结构 什么是堆 堆是一棵具有特定性质的二叉树,堆的基本要求是堆中所有结点的值必须大于等于(或小于等于)其孩子结点的值,这也 ...
- 精简ABP的模块依赖
ABP的模块非常方便我们扩展自己的或使用ABP提供的模块功能,对于ABP自身提供的模块间的依赖关系想一探究竟,并且试着把不必要的模块拆掉,找到那部分核心模块.本次使用的是AspNetBoilerpla ...
- 泛微OA e-cology 数据库接口信息泄露学习
泛微OA e-cology 数据库接口信息泄露 漏洞信息 攻击者可通过存在漏洞的页面直接获取到数据库配置信息.如果攻击者可直接访问数据库,则可直接获取用户数据,甚至可以直接控制数据库服务器:会将当前连 ...
- SQL 练习13
查询没学过"张三"老师讲授的任一门课程的学生姓名 SELECT * from Student WHERE SId not in ( SELECT SC.SId from Teach ...