前言

這篇重點介紹一下代碼編程的注釋風格和注釋文檔生成工具

注釋的原則是有助于對程序的閱讀理解以及提供二次開發(fā)所需文檔，注釋的方式有很多，但是業(yè)內(nèi)常用的規(guī)范是 Doxygen 代碼注釋規(guī)范。遵循原則為，說明性文件、函數(shù)接口必須充分注釋說明。全局變量需要說明功能及取值范圍，需要自行處理資料函數(shù)需要加上使用警告信息。
注意：

不要使用注釋來屏蔽代碼。

關于函數(shù)和局部變量的注釋，當代碼已經(jīng)可自注釋時，不用添加多余的注釋。

簡介

Doxygen 規(guī)范簡要的說，Doxygen 注釋塊其實就是在C、C++注釋塊的基礎添加一些額外標識，使 Doxygen 把它識別出來, 并將它通過對應得工具生成的說明文檔。

文件注釋

文件注釋通常放在整個文件開頭，如說明文件名、作者、日期、描述或版本等諸多信息，具體參數(shù) Doxygen 的文件注釋風格。

 1/**  2 * @file      文件名  3 * @brief     簡介  4 * @details   細節(jié)  5 * @mainpage  工程概覽  6 * @author    作者  7 * @email     郵箱  8 * @version   版本號  9 * @date      年-月-日 10 * @license   版權(quán) 11 */

我常用的風格如下：

 1/**  2 **********************************************************************************************************************  3 * @file    adcDrive.c  4 * @author  const-zpc  5 * @date    2020-7-20  6 * @brief   該文件提供ADC驅(qū)動功能，以管理ADC驅(qū)動的以下功能：  7 *           + 初始化  8 *           + ADC數(shù)據(jù)  9 * 10 ********************************************************************************************************************** 11 * @attention 12 * 暫無 13 * 14 ********************************************************************************************************************** 15 */

類/結(jié)構(gòu)體注釋

類或者結(jié)構(gòu)體定義的注釋方式非常簡單，使用@brief后面填寫類的概述，換行填寫類的詳細信息

/** * @brief   CAN發(fā)送幀類型結(jié)構(gòu)體定義. */typedef struct { uint32_t id; /*!< 幀的標識符ID */ CAN_IdTypeDef emIdType;/*!< 幀的類型 */ CAN_RtrTypeDef emRtrType;/*!< 幀的格式 */ uint8_t lenth; /*!< 幀的數(shù)據(jù)長度 */ uint8_t data[8]; /*!< 幀的數(shù)據(jù)內(nèi)容 */} 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)數(shù)據(jù)幀 */ CAN_REMOTE_FRAME /*!< (1)遠程幀 */} CAN_RtrTypeDef;

函數(shù)

 1/**  2 * @brief      讀取指定CAN接收幀的數(shù)據(jù)信息.  3 *  4 * @note       建議先調(diào)用函數(shù)...  5 * @param[in]  rxIndex g_arrtCANRxFrameInfo 的索引值  6 * @param[in,out] pData - CAN幀數(shù)據(jù)內(nèi)容指針.  7 * @param[out] pLength - CAN幀數(shù)據(jù)長度.  8 * @retval     數(shù)據(jù)長度  9 */ 10int CAN_ReadRxFrameInfo(uint16_t rxIndex, uint8_t *pData, uint8_t *pLength) 11{ 12 ... 13}

文檔生成軟件

Doxygen 能將程序中的特定批注轉(zhuǎn)換成為說明文檔。他可以依據(jù)程序本身的結(jié)構(gòu)，將程序中按規(guī)范注釋的批注經(jīng)過處理生成一個純粹的參考手冊，通過提取代碼結(jié)構(gòu)或借助自動生成的包含依賴圖、繼承圖以及協(xié)作圖來可視化文檔之間的關系，Doxygen生成的幫助文檔的格式可以是 CHM、RTF、PostScript、PDF、HTML等。

Doxygen是一種開源跨平臺的，以類似JavaDoc風格描述的文檔系統(tǒng)，完全支持 C、C++、Java、Objective-C 和 IDL 語言，部分支持 PHP、C#。注釋的語法與 Qt-Doc、Kdoc 和 JavaDoc 兼容。Doxygen 可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線LATE、RTF參考手冊。

軟件截圖