前言

这篇重点介绍一下代码编程的注释风格和注释文档生成工具

注释的原则是有助于对程序的阅读理解以及提供二次开发所需文档，注释的方式有很多，但是业内常用的规范是 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后面填写类的概述，换行填写类的详细信息

/** * @brief   CAN发送帧类型结构体定义. */typedef struct { uint32_t id; /*!< 帧的标识符ID */ CAN_IdTypeDef emIdType;/*!< 帧的类型 */ CAN_RtrTypeDef emRtrType;/*!< 帧的格式 */ uint8_t lenth; /*!< 帧的数据长度 */ uint8_t data[8]; /*!< 帧的数据内容 */} CAN_TxFrameType;

---

枚举注释

/** * @brief  CAN使能/禁止枚举定义 */typedef enum{ CAN_DISABLE = 0, /*!< (0)禁止 */ CAN_ENABLE = !CAN_DISABLE/*!< (1)使能 */}CAN_EnableTypeDef; /** * @brief   CAN帧的格式枚举定义. */typedef enum { CAN_DATA_FRAME = 0, /*!< (0)数据帧 */ CAN_REMOTE_FRAME /*!< (1)远程帧 */} CAN_RtrTypeDef;

---

函数

 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参考手册。

软件截图

根据上述定义的注释通过工具生成文档部分截图：

---