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協議棧參數配置（廣播、連接、安全等）相關宏定義，協議棧各模塊句柄等全局參數
* @{
*/
/** @} 協議棧用全局參數 */
Reference