目录一、文件注释,放于文件的开头
二、函数注释,放于函数声明前
三、数据结构注释,放于数据结构定义前
四、宏定义注释,放于宏定义上方或者右侧
五、 全局和静态变量注释
六、常用标签命令关键字
嵌入式C语言开发中通常使用Doxygen进行文档的生成。Doxygen支持多种格式,非常灵活,但排版不好就会显的比较杂乱,不便于阅读。下面给出一份注释模板。
一、文件注释,放于文件的开头
/**
* @file
* @briefThis is a brief description.
* @details This is the detail description.
* @authorauthor
* @date date
* @version v1.0
* @par Copyright(c): abc corporation
* @par History:
*version: author, date, desc\n
*/
@file 后面貌似不能加文件名,否则不能识别文件头;Doxygen生成示意图:
二、函数注释,放于函数声明前
/**
/**
* This is a brief description.
* This is a detail description.
* @param[in]inArgName input argument description.
* @param[out]outArgName output argument description.
* @retvalOK成功
* @retvalERROR错误
* @par 标识符
* 保留
* @par 其它
* 无
* @par 修改日志
* XXX于2020-07-06创建
*/
int cstyle( int inArgName, int outArgName);
Doxygen生成示意图:
三、数据结构注释,放于数据结构定义前
/**
* @briefThis 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 a0
#define b0/*!< 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) @file --> 文件声明,即当前文件名
2) @author --> 作者
3) @version --> 版本,
4) @todo --> 改进,可以指定针对的版本
模块信息:
1) @var --> 模块变量说明
2) @typedef --> 模块变量类型说明
函数信息:
1) @param --> 参数说明
2) @arg --> 列表说明参数信息
3) @return --> 返回值说明
4) @retval --> 返回值类型说明
5) @note --> 注解
提醒信息:
1) @brief --> 摘要,即当前文件说明
2) @see --> 参看
3) @attention --> 注意
4) @bug --> 问题
5) @warning --> 警告
6) @sa --> 参考资料