Doxygen 注释语法和使用

本文链接： https://blog.csdn.net/qq_41204464/article/details/102458103

注释格式

块注释建议统一使用

/**

*

……

*/

行注释建议统一使用

///…

/** …… */

由于Doxygen 对于批注是视为在解释后面的程序代码。（以上默认在解释后面的程序）

例如:

扫描二维码关注公众号，回复： 7581269 查看本文章

  /**
   * @brief Override function Plan in parent class Planner. 
   * @param planning_init_point  
   * @param frame   Current planning framework. (track node)
   * @param reference_line_info 。
   * @return OK if planning succeeds; error otherwise.
   */
  apollo::common::Status PlanOnReferenceLine(
      const common::TrajectoryPoint& planning_init_point, Frame* frame,
      ReferenceLineInfo* reference_line_info) override;

针对一些常用的指令做说明：

@file	档案的批注说明。
@author	作者的信息
@brief	用于class 或function的批注中，后面为class 或function的简易说明。
@param	格式为 @param arg_name 参数说明主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。
@return	后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。
@retval	格式为 @retval value 传回值说明主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

如果要批注前面的程序代码则需用下面格式的批注符号。

/*!< ... 批注 ... */
/**< ... 批注 ... */ （推荐）
//!< ... 批注 ...
///< ... 批注 ... （推荐）

例如：

using apollo::common::ErrorCode;              ///<错误码
using apollo::common::Status;                 ///<状态

2. 文件注释

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

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

例如：

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

生成文档效果

3. 类定义注释

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

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

例如：

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

生成文档效果

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

4. 常量/变量的注释

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

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

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

代码前注释

/// 注释
常量/变量

例如：

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

代码后注释

常量/变量 ///< 注释

例如：

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

生成文档效果

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

生成文档效果

其他

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

命令	生成字段名	说明
`@see`	参考
`@class`	引用类	用于文档生成连接
`@var`	引用变量	用于文档生成连接
`@enum`	引用枚举	用于文档生成连接
`@code`	代码块开始	与`@endcode`成对使用
`@endcode`	代码块结束	与`@code`成对使用
`@bug`	缺陷	链接到所有缺陷汇总的缺陷列表
`@todo`	TODO	链接到所有TODO 汇总的TODO 列表
`@example`	使用例子说明
`@remarks`	备注说明
`@pre`	函数前置条件
`@deprecated`	函数过时说明

按照类型来注释

1）文件注释

/**
* @file  CommonType.h  
* @brief 常见类型定义
* @author       Vincent
* @date     2015-5-24 
* @version  A001 
* @copyright Vincent                                                              
*/

2）函数注释

/** 
 * 读取文件
 * @param[in]    fileNameLen    文件名长度
 * @param[in]   fileName    文件名
 * @param[in]    dataLen        数据长度
 * @param[out]  fileData    输出数据
 * @return        0，执行成功，非0，失败，详见
 * @ref            RetCode.h
 * @see
 * @note
 */ 
UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData);

3）类型/宏定义注释

/**
* 2字节字符类型                                                                 
*/
typedef unsigned short WORD;

4）枚举/结构注释

/**  枚举类型*/  
enum COLOR{
    RED=0,    ///<  红色 
    GREEN=1,///<  绿色 
    YELLOW=2///<  黄色 
};

希望对你有帮助。