Doxygen简单注释语法说明

一、个人想法

随着进一步的学习，我也了解到了Doxygen语法注释的好处以及用法，我感觉这是一个很好的注释方法，能让人一目了然明白代码的作用。还能够使用官网的工具生成整个代码的注释，能更好的读懂代码。在今后的敲代码生涯中我也要尽可能的用这个语法规范我的程序。(其实例如正点原子STM32代码的注释就是用了这种语法注释，只是当初我们可能没有了解这种语法注释而已)

二、语法简介

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。提供了一套注释方式便于把代码中的注释生成说明文档。
很多语言都适用，例如：C，C#,Python,java等

三、语法说明

1、简单注释

• 单行注释：///或者//!
• 多行注释：/**或者/*!

2、文件注释

文件注释通常放在整个文件开头。

 1. /**
 2. @file 文件名
 3. @brief 简介
 4. @details 细节
 5. @mainpage 工程概览
 6. @author 作者
 7. @email 邮箱
 8. @version 版本号
 9. @date 年-月-日
 10. @license 版权
 */

例如：

 1. /**
 2. @file Test.h
 3. @brief 测试头文件
 4. @details 这个是测试Doxygen
 5. @mainpage 工程概览
 6. @author jdzhangxin
 7. @email [email protected]
 8. @version 1.0.0
 9. @date 2017-11-17
 */

用工具生成的文档效果如下：

3 、类定义

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

 1. /**
 2. @brief 类的简单概述
 3. 类的详细概述
 */

例如

 - /**
 - @brief 测试类
 - 主要用来演示Doxygen类的注释方式
 */
 class Test{
 };

4、变量常量的注释

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

• 全局常量变量
• 宏定义
• 类/结构体/联合体的成员变量
• 枚举类型的成员

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

• 代码前注释

/// 注释
常量/变量

例如：

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

• 代码后注释

常量/变量 ///< 注释
例如：

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

5. 函数注释

• 简约注释

函数注释主要包含函数简介(@brief)、参数说明(’@param’)、返回说明(@return)和返回值说明(@retval)四部分。

 - /**
 - @brief 函数简介
 -  4. @param 形参 参数说明
 - @param 形参 参数说明
 - @return 返回说明
 -   @retval 返回值说明
 */

• 详细注释

可以根据需要添加详细说明(@detail)、注解(@note)、注意(@attention)、警告(@warning)或者异常(@exception)等。

 1. /**
 2. @brief 函数简介
 3. @detail 详细说明
 4. 
 5. @param 形参 参数说明
 6. @param 形参 参数说明
 7. @return 返回说明
 8.   @retval 返回值说明
 9. @note 注解
 10. @attention 注意
 11. @warning 警告
 12. @exception 异常
 */

例子
以main()函数为例添加函数注释。

 1. /**
 2. @brief 主函数
 3. @details 程序唯一入口
 4.  5. @param argc 命令参数个数
 6. @param argv 命令参数指针数组
 7. @return 程序执行成功与否
 8.     @retval 0 程序执行成功
 9.     @retval 1 程序执行失败
 10. @note 这里只是一个简单的例子
*/
int main(int argc, char* argv[])

其他

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

命令 生成字段名 说明

后记

主要的语法就是这些，如果按照这种注释来经常注释，会对整个程序的框架有很好的理解作用，我觉得无论代码的大小都要尽量用这种注释语法来约束自己。虽然小容量代码可能很快就看懂了，但是习惯都是慢慢养成的。

本文参考简书上面的博客 https://www.jianshu.com/p/9464eca6aefe