背景
這一塊的內容更多的是作為了解，但是可以以這樣的規范作為自己的編程注釋習慣，提高自己的軟實力。
Doxygen注釋語法
注釋格式
塊注釋建議統一使用
/**
……
***/
行注釋建議統一使用
///< …
/** …… */
Doxygen常用注釋命令
@exception <exception-object> {exception description} 對一個異常對象進行注釋。
@warning {warning message } 一些需要注意的事情
@todo { things to be done } 對將要做的事情進行注釋，鏈接到所有TODO 匯總的TODO 列表
@bug 缺陷，鏈接到所有缺陷匯總的缺陷列表
@see {comment with reference to other items } 一段包含其他部分引用的注釋，中間包含對其他代碼項的名稱，自動產生對其的引用鏈接。
@relates <name> 通常用做把非成員函數的注釋文檔包含在類的說明文檔中。
@since {text} 通常用來說明從什么版本、時間寫此部分代碼。
@deprecated
@pre { description of the precondition } 用來說明代碼項的前提條件。
@post { description of the postcondition } 用來說明代碼項之后的使用條件。
@code 在注釋中開始說明一段代碼，直到@endcode命令。
@endcode 注釋中代碼段的結束。
@code .. @endcode 包含一段代碼
@addtogroup 添加到一個組。
@brief 概要信息
@deprecated 已廢棄函數
@details 詳細描述
@note 開始一個段落，用來描述一些注意事項
@par 開始一個段落，段落名稱描述由你自己指定
@param 標記一個參數的意義
@fn 函數說明
@ingroup 加入到一個組
@return 描述返回意義
@retval 描述返回值意義
@include 包含文件
@var、@enum、@struct、@class 對變量、美劇、結構體、類等進行標注
Doxygen注釋示例
1.項目注釋
項目注釋塊用於對項目進行描述，每個項目只出現一次，一般可以放在main.c主函數文件頭部。對於其它類型的項目，置於定義項目入口函數的文件中。對於無入口函數的項目，比如靜態庫項目，置於較關鍵且不會被外部項目引用的文件中。
項目注釋塊以/** @mainpage開頭，以*/結束。包含項目描述、及功能描述、用法描述、注意事項4個描述章節。
項目描述章節描述項目名稱、作者、代碼庫目錄、項目詳細描述4項內容，建議采用HTML的表格語法進行對齊描述。
功能描述章節列舉該項目的主要功能。
用法描述章節列舉該項目的主要使用方法，主要針對動態庫、靜態庫等會被其它項目使用的項目。對於其它類型的項目，該章節可省略。
注意事項章節描述該項目的注意事項、依賴項目等相關信息。
要善於使用表格及一些標號語句
例如
/**@mainpage 春節12響固件程序
* <table>
* <tr><th>Project <td>dozen_bangs
* <tr><th>Author <td>李長條
* <tr><th>Source <td>D:\workspace\demo_project\examples\dozen_bangs\dozen_bangs-doxygen
* </table>
* @section 項目詳細描述
* 不讓地球繼續流浪。
*
* @section 功能描述
* -# 破壞
*
* @section 用法描述
* -# 用頂針
*
* @section 固件更新
* <table>
* <tr><th>Date <th>H_Version <th>S_Version <th>Author <th>Description </tr>
* <tr><td>2018/08/17 <td>1.0 <td>S02010041808171 <td>wanghuan <td>創建初始版本 </tr>
* <tr><td>2019/06/24 <td>1.3 <td>S02010041906241 <td>wanghuan <td>
* -# 無
* </tr>
* </table>
**********************************************************************************
*/
2.文件注釋
文件注釋塊對源代碼文件進行注釋，包括頭文件（.h）、C++文件（.cpp）或C文件（*.c）。文件注釋塊置於對應文件的開頭，至少包括文件名（@file）、文件簡要說明（@brief）、作者（@author）、創建日期（@date）和版本號（@version）5個標記。如下所示：
/**@file main.c
* @brief 項目主函數文件
* @details 主要包含協議應用棧程序框架，main函數入口
* @author 李長條
* @date 2018-8-17
* @version V1.0
* @copyright Copyright (c) 2050
**********************************************************************************
* @attention
* SDK版本：v2050.0.0
* @par 修改日志:
* <table>
* <tr><th>Date <th>Version <th>Author <th>Description
* <tr><td>2010/02/17 <td>1.0 <td>wanghuan <td>創建初始版本
* </table>
*
**********************************************************************************
*/
3.函數注釋
該注釋塊對函數進行描述，位於對應函數的定義上方。
函數注釋塊包含以下內容：
- 簡要說明標記（@brief），內容為方法 / 函數的簡要說明。
- 詳細描述，詳細描述與@brief標記之間空一行”\n”或者使用@details。
- 若干個參數描述標記（@param），數量與該方法的輸入參數個數相同。格式為：“@param 參數名稱 參數說明”。
- 返回值標記（@return），描述該方法的返回值，格式為：“@return 返回值類型 返回值描述”。若返回值為void類型，則省略該標記。
- 返回值說明（@retval），對具體返回值進行描述說明。
- 特殊標記
-：生成一個黑心圓.
-#：指定按順序標記。
::：指定連接函數功能。（注：空格和“:”有連接功能,但建議還是使用”::”。只對函數有用。）
以下是一個函數注釋塊實例，實際根據情況增減：
/**@brief 注冊函數
* @param[in] *data 上報數據指針
* @param[in] len 上報數據長度
* @param[in] report_fail_try_type 上報失敗重新注冊類型 \n
* @ref NB_REPFAIL_REG_TRY 出錯立即重試 \n
* @ref NB_REPFAIL_REG_DELAY_TRY 出錯延緩重試，在延遲期間如果正常則重新延緩，適用於高頻率上報（上報失敗重新注冊超時15min） \n
* @ref NB_REPFAIL_REG_NO_TRY 出錯不重試
* @return 函數執行結果
* - NB_NOTIFY_SUCCESS 上報成功
* - NB_NOTIFY_FAIL 上報失敗
* - NB_IOT_REGIST_FAILED 注冊失敗返回
* - Others 其他錯誤
* @par 示例:
* @code
* int ret = register_all(&data, len, RT_TYPE_T1)
* @endcode
* @see :: xx表
*/
4. 枚舉、結構體等注釋
/**@enum msg_types
* @brief 定義驅動上報應用消息類型
*/
/**@struct info
* @brief 信息結構體 \n
* 定義存儲的信息
*/
typedef struct 結構體名字
{
成員1, ///< 簡要說明文字 */ 如果不加<，則會認為是成員2的注釋
成員2, ///< 簡要說明文字
成員3, ///< 簡要說明文字
}結構體別名；
5.模塊注釋
模塊注釋用於將一系列相關功能的函數、枚舉、結構等歸入一個模塊並進行描述。模塊注釋塊包括模塊起始注釋塊及模塊結束注釋塊兩個部分。
模塊起始注釋塊包含模塊名稱標記（@defgroup）、模塊簡介標記（@brief）、模塊詳細描述及模塊起始標記（@{）4個部份。
模塊結束注釋用於結束一模塊描述定義，格式為/** @} */。與模塊起始注釋塊成對出現。包含在模塊起始注釋塊與結束注釋塊之間的所有內容將歸入該模塊。
若需要將其它文件中定義的內容歸入一個已定義的模塊，可使用簡略的模塊起始注釋塊與結束注釋塊括起需要歸入該模塊的內容。簡略的模塊起始注釋塊僅包含相同的模塊名稱標記（@defgroup）。
如下所示：
/**@defgroup bsp_me3616 Bsp me3616 driver module.
* @{
* @ingroup bsp_drivers
* @brief 使用該驅動之前，先進行驅動句柄的實例注冊. \n
* ME3616驅動支持雲平台Onenet和OceanConnect \n
* 當使能GPS驅動使能時，支持GPS操作
*/
/** @} bsp_me3616*/
5.分組注釋
自定義命名的一組內容注釋
/**@name 協議棧用全局參數
* @brief 協議棧參數配置（廣播、連接、安全等）相關宏定義，協議棧各模塊句柄等全局參數
* @{
*/
/** @} 協議棧用全局參數 */