目录
嵌入式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
*/
- 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) @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 --> 参考资料