C语言中的Doxygen注释模板

嵌入式C语言开发中通常使用Doxygen进行文档的生成。Doxygen支持多种格式，非常灵活，但排版不好就会显的比较杂乱，不便于阅读。下面给出一份注释模板。

一、文件注释，放于文件的开头

/**
* @file         
* @brief		This is a brief description.
* @details	    This is the detail description.
* @author		author
* @date		    date
* @version	    v1.0
* @par Copyright(c): 	abc corporation
* @par History:         
*	version: author, date, desc\n
*/

@file 后面貌似不能加文件名,否则不能识别文件头;Doxygen生成示意图:

二、函数注释，放于函数声明前

 /**
 * @brief		This is a brief description.
 * @details	    This is the detail description. 
 * @param[in]	inArgName input argument description.
 * @param[out]	outArgName output argument description. 
 * @retval		OK		成功
 * @retval		ERROR	错误 
 * @par 标识符
 * 		保留
 * @par 其它
 * 		无
 * @par 修改日志
 * 		XXX于2020-07-06创建
 */
int cstyle( int inArgName, int outArgName);

Doxygen生成示意图:

三、数据结构注释，放于数据结构定义前

/** 
 * @brief		This is a brief description.
 * @details	    This is the detail description. 
 */
typedef struct
{
	int var1; /*!< Detailed description of the member var1 */
	int var2; /*!< Detailed description of the member var2*/
	int var3; /*!< Detailed description of the member var3 */
} abc;

Doxygen生成示意图:

四、宏定义注释，放于宏定义上方或者右侧

/** Description of the macro a */
#define a		0

#define b		0  /*!< Description of the macro b */

Doxygen生成示意图:

五、 全局和静态变量注释

/**  Description of global variable  */
int g_qwe = 0;
 
int static  s_asd = 0; /*!< Description of static variable */

Doxygen生成示意图:

六、常用标签命令关键字

1. 文件信息：
   　 1) @file --> 文件声明，即当前文件名
   　 2) @author --> 作者
   　 3) @version --> 版本，
   　 4) @todo --> 改进，可以指定针对的版本

2. 模块信息：
   　 1) @var --> 模块变量说明
   　 2) @typedef --> 模块变量类型说明

3. 函数信息：
   　 1) @param --> 参数说明
   　 2) @arg --> 列表说明参数信息
   　 3) @return --> 返回值说明
   　 4) @retval --> 返回值类型说明
   　 5) @note --> 注解

4. 提醒信息：
   　 1) @brief --> 摘要，即当前文件说明
   　 2) @see --> 参看
   　 3) @attention --> 注意
   　 4) @bug --> 问题
   　 5) @warning --> 警告
   　 6) @sa --> 参考资料