前言

這篇重點(diǎn)介紹一下代碼編程的注釋風(fēng)格和注釋文檔生成工具

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

注意：

1. 不要使用注釋來(lái)屏蔽代碼。
2. 關(guān)于函數(shù)和局部變量的注釋，當(dāng)代碼已經(jīng)可自注釋時(shí)，不用添加多余的注釋。

簡(jiǎn)介

Doxygen 規(guī)范簡(jiǎn)要的說(shuō)，Doxygen 注釋塊其實(shí)就是在C、C++注釋塊的基礎(chǔ)添加一些額外標(biāo)識(shí)，使 Doxygen 把它識(shí)別出來(lái), 并將它通過(guò)對(duì)應(yīng)得工具生成的說(shuō)明文檔。

文件注釋

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

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

我常用的風(fēng)格如下：

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

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

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

/**
 * @brief   CAN發(fā)送幀類型結(jié)構(gòu)體定義.
 */
typedef struct {
    uint32_t id;      /*!< 幀的標(biāo)識(shí)符ID */
    CAN_IdTypeDef emIdType;/*!< 幀的類型 */
    CAN_RtrTypeDef emRtrType;/*!< 幀的格式 */
    uint8_t lenth;      /*!< 幀的數(shù)據(jù)長(zhǎng)度 */
    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)遠(yuǎn)程幀 */
} 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ù)長(zhǎng)度.
 8  * @retval     數(shù)據(jù)長(zhǎng)度
 9  */
10int CAN_ReadRxFrameInfo(uint16_t rxIndex, uint8_t *pData, uint8_t *pLength)
11{
12    ...
13}

文檔生成軟件

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

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

軟件截圖

根據(jù)上述定義的注釋通過(guò)工具生成文檔部分截圖：