Doxygen 注释规范

文件头注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/* polyspace<MISRA-C3:1.1:Not a defect:Justify with annotations> */
/**
 * @file       Adc.h
 * @author     linmin
 * @brief      This file provides ADC related function declarations and related macro definitions.
 *
 * @par        Platform File
 *
 *
 * @copyright (c) 2022 AOTECAR, all rights reserved.
 */

/*------------------------------------------------------------------------------
                 R E V I S I O N   H I S T O R Y
 -------------------------------------------------------------------------------
   Date           Version        Author       Description
 -------------------------------------------------------------------------------
  2022.7.5       01.00.00       Liubingqian        Creation
  2022.11.16     1.01.01        linmin
  ------------------------------------------------------------------------------*/

includes 分区

1
2
3
/*----------------------------------------------------------------------------*/
/*                                 Includes                                   */
/*----------------------------------------------------------------------------*/

External 声明分区

1
2
3
/*----------------------------------------------------------------------------*/
/*                External declaration of global RAM-Variables                */
/*----------------------------------------------------------------------------*/

Global data 分区

1
2
3
/*----------------------------------------------------------------------------*/
/*                             Global data at RAM                             */
/*----------------------------------------------------------------------------*/

函数注释模板

1
2
3
4
5
6
7
/**
* @brief			None
* @param[in]		None
* @param[out]		None
* @pre				None
* @post 			None
*/

常用 Doxygen 命令

命令 说明 示例
@file 档案的批注说明 @file main.c
@author 作者的信息 @author John Doe
@brief 用于class或function的简易说明 @brief 本函数负责打印错误信息
@param 参数说明，后接参数名再接说明 @param[in] str 输入字符串
@return 描述返回值情况 @return 成功返回TRUE，失败返回FALSE
@retval 描述返回值类型 @retval NULL 空字符串
@note 注解 @note 该函数线程不安全
@attention 注意 @attention 需要先初始化
@warning 警告信息 @warning 勿在中断中调用
@enum 引用枚举 @enum CTest::MyEnum
@var 引用变量 @var CTest::m_FileKey
@class 引用类 @class CTest "inc/class.h"
@exception 可能产生的异常 @exception 可能产生内存溢出
@todo 将要做的事情 @todo 添加参数校验
@see 引用其他代码项 @see init() close()
@relates 将非成员函数文档包含在类中 @relates <name>
@since 说明从哪个版本开始 @since v1.2.0
@code 开始代码段 @code
@endcode 代码段结束 @endcode
@pre 前提条件 @pre 必须先调用init()
@post 使用条件 @post 使用后需调用release()
@deprecated deprecated标记 @deprecated 请使用newFunc()
@defgroup 模块名 @defgroup MODULE_NAME
@fn 声明函数 @fn void func(void)

语句注释

使用 //< 作为行尾注释标记：

1
int x; //<

特殊命令

addtogroup

1
2
3
4
5
6
7
/**
* @addtogroup Typedefs
* @{
*/
....

/** @} *//* Typedefs definition */

graph 相关命令

命令 说明
@callgraph 生成调用图（需HAVE_DOT=YES）
@callergraph 生成调用者图
@hidecallgraph 不创建调用图
@hidecallergraph 不创建调用者图