芯耀
251
這篇重點(diǎn)介紹一下代碼編程的注釋風(fēng)格和注釋文檔生成工具
注釋的原則是有助于對(duì)程序的閱讀理解以及提供二次開發(fā)所需文檔，注釋的方式有很多，但是業(yè)內(nèi)常用的規(guī)范是 Doxygen 代碼注釋規(guī)范。遵循原則為，說明性文件、函數(shù)接口必須充分注釋說明。全局變量需要說明功能及取值范圍，需要自行處理資料函數(shù)需要加上使用警告信息。
注意：
1 不要使用注釋來屏蔽代碼。
2 關(guān)于函數(shù)和局部變量的注釋，當(dāng)代碼已經(jīng)可自注釋時(shí)，不用添加多余的注釋。
簡(jiǎn)介
Doxygen 規(guī)范簡(jiǎn)要的說，Doxygen 注釋塊其實(shí)就是在C、C++注釋塊的基礎(chǔ)添加一些額外標(biāo)識(shí)，使 Doxygen 把它識(shí)別出來, 并將它通過對(duì)應(yīng)得工具生成的說明文檔。
文件注釋
文件注釋通常放在整個(gè)文件開頭，如說明文件名、作者、日期、描述或版本等諸多信息，具體參數(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??*?暫無
13??*
14??**********************************************************************************************************************
15??*/
類/結(jié)構(gòu)體注釋
類或者結(jié)構(gòu)體定義的注釋方式非常簡(jiǎn)單，使用@brief后面填寫類的概述，換行填寫類的詳細(xì)信息
枚舉注釋
函數(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)換成為說明文檔。他可以依據(jù)程序本身的結(jié)構(gòu)，將程序中按規(guī)范注釋的批注經(jīng)過處理生成一個(gè)純粹的參考手冊(cè)，通過提取代碼結(jié)構(gòu)或借助自動(dòng)生成的包含依賴圖、繼承圖以及協(xié)作圖來可視化文檔之間的關(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ù)上述定義的注釋通過工具生成文檔部分截圖：
