doxygen 注释规范_Doxygen简明注释语法

语法简介

Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。提供了一套注释方式便于把代码中的注释生成说明文档。

很多开源项目都在使用,例如:

下面是常用的注释简介。

1. 简单注释

单行注释:///或者//!

多行注释:/**或者/*!

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

*/

生成文档效果

9464eca6aefe

3. 类定义注释

类定义的注释方式非常简单,使用@brief后面填写类的概述,换行填写类的详细信息。

/**

* @brief 类的简单概述

* 类的详细概述

*/

例如:

/**

* @brief 测试类

* 主要用来演示Doxygen类的注释方式

*/

class Test{

};

生成文档效果

9464eca6aefe

9464eca6aefe

命名空间、结构体、联合体、枚举定义与类定义注释方式一致。

4. 常量/变量的注释

常量/变量包括以下几种类型

全局常量变量

宏定义

类/结构体/联合体的成员变量

枚举类型的成员

注释分为两种方式,可根据具体情况自行选择

代码前注释

/// 注释

常量/变量

例如:

/// 缓存大小

#define BUFSIZ 1024*4

代码后注释

常量/变量 ///< 注释

例如:

#define BUFSIZ 1024*4 ///< 缓存大小

生成文档效果

9464eca6aefe

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[])

生成文档效果

9464eca6aefe

其他

下面一些标注方式可以根据需要选择使用。

命令

生成字段名

说明

@see

参考

@class

引用类

用于文档生成连接

@var

引用变量

用于文档生成连接

@enum

引用枚举

用于文档生成连接

@code

代码块开始

与@endcode成对使用

@endcode

代码块结束

与@code成对使用

@bug

缺陷

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

@todo

TODO

链接到所有TODO 汇总的TODO 列表

@example

使用例子说明

@remarks

备注说明

@pre

函数前置条件

@deprecated

函数过时说明

  • 3
    点赞
  • 12
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值