芯耀
1651
这篇重点介绍一下代码编程的注释风格和注释文档生成工具
注释的原则是有助于对程序的阅读理解以及提供二次开发所需文档，注释的方式有很多，但是业内常用的规范是 Doxygen 代码注释规范。遵循原则为，说明性文件、函数接口必须充分注释说明。全局变量需要说明功能及取值范围，需要自行处理资料函数需要加上使用警告信息。
注意：
1 不要使用注释来屏蔽代码。
2 关于函数和局部变量的注释，当代码已经可自注释时，不用添加多余的注释。
简介
Doxygen 规范简要的说，Doxygen 注释块其实就是在C、C++注释块的基础添加一些额外标识，使 Doxygen 把它识别出来, 并将它通过对应得工具生成的说明文档。
文件注释
文件注释通常放在整个文件开头，如说明文件名、作者、日期、描述或版本等诸多信息，具体参数 Doxygen 的文件注释风格。
1/**
2 * @file 文件名
3 * @brief 简介
4 * @details 细节
5 * @mainpage 工程概览
6 * @author 作者
7 * @email 邮箱
8 * @version 版本号
9 * @date 年-月-日
10 * @license 版权
11 */
我常用的风格如下：
1/**
2 **********************************************************************************************************************
3 * @file adcDrive.c
4 * @author const-zpc
5 * @date 2020-7-20
6 * @brief 该文件提供ADC驱动功能，以管理ADC驱动的以下功能：
7 * + 初始化
8 * + ADC数据
9 *
10 **********************************************************************************************************************
11 * @attention
12 * 暂无
13 *
14 **********************************************************************************************************************
15 */
类/结构体注释
类或者结构体定义的注释方式非常简单，使用@brief后面填写类的概述，换行填写类的详细信息
枚举注释
函数
1/**
2 * @brief 读取指定CAN接收帧的数据信息.
3 *
4 * @note 建议先调用函数...
5 * @param[in] rxIndex g_arrtCANRxFrameInfo 的索引值
6 * @param[in,out] pData - CAN帧数据内容指针.
7 * @param[out] pLength - CAN帧数据长度.
8 * @retval 数据长度
9 */
10int CAN_ReadRxFrameInfo(uint16_t rxIndex, uint8_t *pData, uint8_t *pLength)
11{
12 ...
13}
文档生成软件
Doxygen 能将程序中的特定批注转换成为说明文档。他可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图、继承图以及协作图来可视化文档之间的关系，Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。
Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持 C、C++、Java、Objective-C 和 IDL 语言，部分支持 PHP、C#。注释的语法与 Qt-Doc、Kdoc 和 JavaDoc 兼容。Doxygen 可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线LATE、RTF参考手册。
软件截图
根据上述定义的注释通过工具生成文档部分截图：
