使用doxygen對c++代碼進行文檔化註釋示例

Doxgen的使用包括兩個方面：
- 一個是代碼的註釋規則；
- 一個是利用doxgen生成相應的HTML和chm文件。

註釋規則

文件註釋

    /*!
    * @file   core.h 
    * @brief  核心類core
    * @author author
    * @date   2016-11-12                                                 
    */

• 1
• 2
• 3
• 4
• 5
• 6

函數註釋

    /*!
     * @param  參數
     * @return 返回值
     * @see    參考對象
     * @note   說明
     */

• 1
• 2
• 3
• 4
• 5
• 6

類/結構體註釋

    /*！@brief 本類的功能：打印錯誤信息  
     *   
     *   程序的核心類core
     *   程序所有的對象基類
     */ 

• 1
• 2
• 3
• 4
• 5

成員變量註釋

    /*！ 成員變量描述 */ 
    int  m_iVar; 

• 1
• 2

或者

    int  m_iVar;     /*!< 成員變量描述 */

• 1

文檔生成

安裝Doxygen

• 安裝 doxygen-1.8.11-setup。
• 安裝 Windows Help Workshop。Doxygen 使用這個工具可以生成 CHM 格式的文檔。

Doxygen的配置使用

1. Wizard=>Project
   打開安裝後的Doxgen窗口，選擇Wizard=>Project，輸入一下內容
   
2. Wizard=>Output
   選擇Wizard=>Output,由於我只需要chm，所以只選擇了prepare for compressed HTML(.chm)
   
3. Expert=>Project
   選擇Expert=>Project,因爲我需要輸出中文，所以我選擇了gbk和Chinese選項
   
4. Expert=>Build
   
   • EXTRACT_ALL 表示：輸出所有的函數，但是private和static函數不屬於其管制。
   • EXTRACT_PRIVATE 表示：輸出private函數。
   • EXTRACT_STATIC 表示：輸出static函數。
   • INTERNAL_DOCS 主要指：是否輸出註解中的@internal部分。如果沒有被啓動，那麼註解中所有的@internal部分都 將在目標幫助中不可見。
   • HIDE_SCOPE_NAMES 表示：域隱藏，建議永遠不要開啓。
   • INLINE_INFO ：如果開啓，那麼在幫助文檔中，inline函數前面會有一個inline修飾詞來標明。
   • SHOW_FILES ：是否顯示文件列表頁面，如果開啓，那麼幫助中會存在一個一個文件列表索引頁面。
     
5. Expert=>Input
   選擇Expert=>Input,覈對你的input選項，如果有源碼之外的文件需要添加，可以在此進行操作，輸入編碼仍然選擇GBK
   
6. Expert=>HTML
   選擇Expert=>HTML，輸出chm的文件名稱，注意必須輸出後綴名稱：.chm。HHC的exe路徑，在你安裝的HTML Help Workshop目錄下。編碼仍然選擇GBK
   
7. Run=>Run doxgen
   選擇Run=>Run doxgen，看見finished就表示大功告成了！
   

8. 完成
   

至此，文檔註釋算是寫完了，當然以上只是一些比較簡單的註釋輸出，更加詳細的大家參照doxgen的文檔吧！

參考內容：
Doxygen使用教程(個人總結)