1.Doxygen簡介
Doxygen是一個程式的文檔産生工具，可以将程式中的注釋轉換成說明文檔或者說是API參考手冊，進而減少程式員整理文檔的時間。當然這裡程式中的注釋需要遵循一定的規則書寫，才能讓Doxygen識别和轉化。
目前Doxygen可處理的程式語言包含C/C++、Java、Objective-C、IDL等，可産生出來的文檔格式有HTML、XML、LaTeX、RTF等，此外還可衍生出不少其它格式，如HTML可以打包成CHM格式，而LaTeX可以通過一些工具産生出PS或是PDF文檔等。
2.
2.Doxygen安裝及使用
安裝清單：
Doxygen： 下載下傳位址，http://doxygen.nl/files/doxygen-1.8.15-setup.exe
HTML Help：微軟官方用于生成HTML格式的help檔案，下載下傳位址，http://go.microsoft.com/fwlink/p/?linkid=14188
Graphviz：一種dot工具可以用來渲染出效果更好的圖表，下載下傳位址，https://graphviz.gitlab.io/_pages/Download/Download_windows.html
windows上安裝很簡單，無需特别設定。
2.1 Doxygen設定
1.向導
2.專家設定
2.1 Project
每個配置項均有詳細滑鼠放置時均有詳細注釋，以下是我的設定可供參考，特别注意語言，避免中文亂碼
2.2 Build
EXTRACT_ALL 表示：輸出所有的函數，但是private和static函數不屬于其管制。
EXTRACT_PRIVATE 表示：輸出private函數。
EXTRACT_STATIC 表示：輸出static函數。同時還有幾個EXTRACT，相應檢視文檔即可。
HIDE_UNDOC_MEMBERS表示：那些沒有使用doxygen格式描述的文檔（函數或類等）就不顯示了。當然，如果EXTRACT_ALL被啟用，那麼這個标志其實是被忽略的。
INTERNAL_DOCS 主要指：是否輸出注解中的@internal部分。如果沒有被啟動，那麼注解中所有的@internal部分都将在目标幫助中不可見。
CASE_SENSE_NAMES 表示：是否關注大小寫名稱，注意，如果開啟了，那麼所有的名稱都将被小寫。對于C/C++這種字母相關的語言來說，建議永遠不要開啟。
HIDE_SCOPE_NAMES 表示：域隐藏，建議永遠不要開啟。
SHOW_INCLUDE_FILES 表示：是否顯示包含檔案，如果開啟，幫助中會專門生成一個頁面，裡面包含所有包含檔案的清單。
INLINE_INFO ：如果開啟，那麼在幫助文檔中，inline函數前面會有一個inline修飾詞來标明。
SORT_MEMBER_DOCS ：如果開啟，那麼在幫助文檔清單顯示的時候，函數名稱會排序，否則按照解釋的順序顯示。
GENERATE_TODOLIST ：是否生成TODOLIST頁面，如果開啟，那麼包含在@todo注解中的内容将會單獨生成并顯示在一個頁面中，其他的GENERATE選項同。
SHOW_USED_FILES ：是否在函數或類等的幫助中，最下面顯示函數或類的來源檔案。
SHOW_FILES ：是否顯示檔案清單頁面，如果開啟，那麼幫助中會存在一個一個檔案清單索引頁面。
2.3 input
2.4 Source Browser
2.5 HTML
2.6 Dot
3 Run 點選運作即可
生成檔案在工程 /doc/html/ble_app_gnt.chm
效果如下：
3. Doxygen注釋文法
3.1 注釋格式
塊注釋建議統一使用
/**
……
*/
行注釋建議統一使用
///< …
/** …… */
3.2 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 對變量、美劇、結構體、類等進行标注
3.3 Doxygen注釋示例
3.3.1 項目注釋
項目注釋塊用于對項目進行描述，每個項目隻出現一次，一般可以放在main.c主函數檔案頭部。對于其它類型的項目，置于定義項目入口函數的檔案中。對于無入口函數的項目，比如靜态庫項目，置于較關鍵且不會被外部項目引用的檔案中。
項目注釋塊以“/** @mainpage”開頭，以“*/”結束。包含項目描述、及功能描述、用法描述、注意事項4個描述章節。
項目描述章節描述項目名稱、作者、代碼庫目錄、項目較長的描述4項内容，建議采用HTML的表格文法進行對齊描述。
功能描述章節列舉該項目的主要功能。
用法描述章節列舉該項目的主要使用方法，主要針對動态庫、靜态庫等會被其它項目使用的項目。對于其它類型的項目，該章節可省略。
注意事項章節描述該項目的注意事項、依賴項目等相關資訊。
要善于使用表格及一些标号語句
/**@mainpage 智能井蓋固件程式
* <table>
* <tr><th>Project <td>ble_app_smc
* <tr><th>Author <td>wanghuan
* <tr><th>Source <td>E:\keil_workspace\NORDIC\nRF52832_htwh_sdk15.0\examples\ble_peripheral\ble_app_smc_freertos-doxygen
* </table>
* @section 項目較長的描述
* 通過智能井蓋管理系統的部署，管理人員通過手機APP與管理平台就能對轄區内井蓋的安裝、開閉、狀态進行管理，出現異常情況及時通知維護人員進行檢修，保障排水正常，保障市民安全。
*
* @section 功能描述
* -# 本工程基于藍牙新品nRF52832開發
* -# 本工程基于藍牙協定棧開發，協定棧版本 SDK-15.0
* -# 智能井蓋采用NB-IoT模組為ME3616
*
* @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>
* -# 電信平台增加上報需應答，應答逾時時間預設40s；\n
* 代碼宏：ME3616_NOTIFY_NEED_RPLY_EN
* -# 新增PSM進入逾時處理，預設逾時處理模組關機，逾時時間預設200s；\n
* 代碼宏：ME3616_PSM_TIMEOUT_HANDLE_EN
* -# 信号強度擷取接口函數修改，增加可靠性，詳見 me3616_getSignal()；
* -# 調試指令新增周期上報測試指令，710A-0D
* </tr>
* </table>
**********************************************************************************
*/ 3.3.2 檔案注釋
檔案注釋塊對源代碼檔案進行注釋，包括頭檔案（*.h）、C++檔案（*.cpp）或C檔案（*.c）。檔案注釋塊置于對應檔案的開頭，至少包括檔案名（@file）、檔案簡要說明（@brief）、作者（@author）、建立日期（@date）和版本号（@version）5個标記。如下所示：
/**@file main.c
* @brief 項目主函數檔案
* @details 主要包含協定應用棧程式架構，main函數入口
* @author wanghuan any question please send mail to [email protected]
* @date 2018-8-17
* @version V1.0
* @copyright Copyright (c) 2018-2020 江蘇亨通光網科技有限公司
**********************************************************************************
* @attention
* 硬體平台:nRF52832_QFAA \n
* SDK版本：nRF5_SDK_15.0.0
* @par 修改日志:
* <table>
* <tr><th>Date <th>Version <th>Author <th>Description
* <tr><td>2018/08/17 <td>1.0 <td>wanghuan <td>建立初始版本
* </table>
*
**********************************************************************************
*/ 3.3.3 函數注釋
該注釋塊對函數進行描述，位于對應函數的定義上方。
函數注釋塊包含以下内容：
- 簡要說明标記（@brief），内容為方法 / 函數的簡要說明。
- 較長的描述，較長的描述與@brief标記之間空一行”\n”或者使用@details。
- 若幹個參數描述标記（@param），數量與該方法的輸入參數個數相同。格式為：“@param 參數名稱 參數說明”。
- 傳回值标記（@return），描述該方法的傳回值，格式為：“@return 傳回值類型 傳回值描述”。若傳回值為void類型，則省略該标記。
- 傳回值說明（@retval），對具體傳回值進行描述說明。
- 特殊标記
-：生成一個黑心圓.
-#：指定按順序标記。
::：指定連接配接函數功能。（注：空格和“:”有連接配接功能,但建議還是使用”::”。隻對函數有用。）
以下是一個函數注釋塊執行個體，實際根據情況增減：
/**@brief NB模組向雲平台上報資料
* @param[in] handle NB模組驅動句柄
* @param[in] *data 上報資料指針
* @param[in] len 上報資料長度
* @param[in] rcc_enabled 上報時是否主動釋放RCC連結
* @param[in] update_enabled 上報時是否更新注冊(隻适用于onenet)
* @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
* 移動平台發送資料 AT+MIPLNOTIFY=0,122553,3308,0,5900,4,4,50,0,0
* 電信平台發送資料 AT+M2MCLISEND=000101
* @endcode
* @see :: ME3616_FxnTable
*/ 3.3.4 枚舉、結構體等注釋
/**@enum NB_msg_types_t
* @brief 定義驅動上報應用消息類型
*/
/**@struct ME3616_info_t
* @brief ME3616資訊結構體 \n
* 定義存儲ME3616的資訊
*/
typedef struct 結構體名字
{
成員1, ///< 簡要說明文字 */ 如果不加<，則會認為是成員2的注釋
成員2, ///< 簡要說明文字
成員3, ///< 簡要說明文字
}結構體别名； 3.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*/ 3.3.5 分組注釋
自定義命名的一組内容注釋
/**@name 協定棧用全局參數
* @brief 藍牙5協定棧參數配置（廣播、連接配接、安全等）相關宏定義，協定棧各子產品句柄等全局參數
* @{
*/
/** @} 協定棧用全局參數 */