前言
這篇重點(diǎn)介紹一下代碼編程的注釋風(fēng)格和注釋文檔生成工具
注釋的原則是有助于對(duì)程序的閱讀理解以及提供二次開發(fā)所需文檔,注釋的方式有很多,但是業(yè)內(nèi)常用的規(guī)范是 Doxygen 代碼注釋規(guī)范。遵循原則為,說(shuō)明性文件、函數(shù)接口必須充分注釋說(shuō)明。全局變量需要說(shuō)明功能及取值范圍,需要自行處理資料函數(shù)需要加上使用警告信息。
注意:
- 不要使用注釋來(lái)屏蔽代碼。
- 關(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ò)工具生成文檔部分截圖:
-
代碼
+關(guān)注
關(guān)注
30文章
4887瀏覽量
70264 -
注釋
+關(guān)注
關(guān)注
0文章
11瀏覽量
6585 -
全局變量
+關(guān)注
關(guān)注
1文章
28瀏覽量
9112
發(fā)布評(píng)論請(qǐng)先 登錄
評(píng)論