GREATers

C-Doxygen简明注释语法

Create on 2020-08-06T08:32:26Z

written by Huang Jiande

## 语法简介

Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。提供了一套注释方式便于把代码中的注释生成说明文档。
 很多开源项目都在使用，例如：

-   [wxWidgets](https://links.jianshu.com/go?to=http%3A%2F%2Fdocs.wxwidgets.org%2F3.0%2F)
-   [clang](https://links.jianshu.com/go?to=http%3A%2F%2Fclang.llvm.org%2Fdoxygen%2Findex.html)

下面是常用的注释简介。

### 1. 简单注释

-   单行注释：`///`或者`//!`
-   多行注释：`/**`或者`/*!`

### 2. 文件注释

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

```c++
/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @email 邮箱
 * @version 版本号
 * @date 年-月-日
 * @license 版权
 */

```

例如：

```c++
/**
 * @file Test.h
 * @brief 测试头文件
 * @details 这个是测试Doxygen
 * @mainpage 工程概览
 * @author jdzhangxin
 * @email jdzhangxin@126.com
 * @version 1.0.0
 * @date 2017-11-17
 */

```

生成文档效果

![](https://tva1.sinaimg.cn/large/0081Kckwgy1gkmci4au99j30mj08g3yp.jpg)

### 3. 类定义注释

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

```c++
 /**
 * @brief 类的简单概述
 * 类的详细概述
 */
```

例如：

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

生成文档效果

![](https://tva1.sinaimg.cn/large/0081Kckwgy1gkmcijazicj30m4035t8m.jpg)

![](https://tva1.sinaimg.cn/large/0081Kckwgy1gkmciflecpj30mh0b0aaj.jpg)

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

### 4. 常量/变量的注释

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

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

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

-   代码前注释

```c++
    /// 注释
    常量/变量
    ```

例如：

```c++
    /// 缓存大小
    #define BUFSIZ 1024*4
    ```

-   代码后注释

```c++
    常量/变量 ///< 注释
    ```

例如：

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

生成文档效果:

![](https://tva1.sinaimg.cn/large/0081Kckwgy1gkmclzfkoej30m4038gli.jpg)

### 5. 函数注释

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

```c++
    /**
     * @brief 函数简介
     *
     * @param 形参 参数说明
     * @param 形参 参数说明
     * @return 返回说明
     *   @retval 返回值说明
     */
    ```

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

```c++
    /**
     * @brief 函数简介
     * @detail 详细说明
     * 
     * @param 形参 参数说明
     * @param 形参 参数说明
     * @return 返回说明
     *   @retval 返回值说明
     * @note 注解
     * @attention 注意
     * @warning 警告
     * @exception 异常
     */
    ```

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

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

生成文档效果

![](https://tva1.sinaimg.cn/large/0081Kckwgy1gkmcip2c3jj30m60j4aay.jpg)

### 其他

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