DOXYGEN簡明實用教程

本文檔主要適用於UbuntuKylin15.04.

Doxygen（http://www.doxygen.nl/download.html）能夠自動根據代碼建立文檔，是一個很是好的工具，能夠支持不少種語言，快速生成類、文件、註釋等一體的文檔，可以輸出html/latex等多種文檔格式。

1、安裝

獲取最新版本，可使用下面的腳本進行安裝。

#須要BISON和FLEX支持。
sudo apt-get install FLEX BISON
git clone https://github.com/doxygen/doxygen.git
cd doxygen
make
sudo make install

或者直接安裝：

#這個是生成類圖的工具，須要預先安裝。
sudo apt-get install graphviz
sudo apt-get install doxygen

2、使用流程

先建立一個控制文檔的模版文件：

doxygen -g doc.dot

進去修改輸入、輸出路徑、各類參數。裏面有詳細的註釋，一看就明白。

gedit doc.dot

生成最終的文檔，將輸出到文檔中制定的OUTPUT_PATH目錄位置。

doxygen doc.dot

3、使用經驗和參數說明

一些經驗，謹供參考：

 -----------------------------------------------------------------------------------

1.全部註釋均可以使用///開始(C++風格)。
2.類體前必須加上///描述，不然會產生警告【Compound 類名 is not documented】
  描述中最好不要帶有此類的類名，不然會產生兩個連接(但指向同一個文件)影響美觀。
3.public和protected會自動生成，可是private要在Expert的Build選項裏勾中EXTRACT_PRIVATE，static成員也是如此。
4.函數註釋方式
 

   /// Constructor【函數描述】
    /// @param [in] pos       The position of Camera in world coordinate         【參數描述1】
    /// @param  [in] lookat    The point Camera looks at in world coordinate    【參數描述2】
   /// BaseCamera( const D3DXVECTOR3& pos, const D3DXVECTOR3& lookat );

5.變量註釋方式
    D3DXVECTOR3 m_Position;    /*!< Camera position point in world coordinate */   或
    D3DXVECTOR3 m_Position;    ///< Camera position point in world coordinate
兩種方式產生的結果不一樣。前者會單獨產生一塊Member Data Documentation註釋，後者會在Pubilc/Protected/Private Attributes變量描述後緊跟註釋。
6.@參數和\參數相同
7.產生描述順序和註釋順序相同，通常風格爲：
 

   /// 函數描述
    /// 
@param
      參數描述
    /// 
@return
      返回值描述
    /// @retval     返回值1     返回值1描述
    /// @retval     返回值2     返回值2描述
    /// @remarks     注意事項
    /// @note    注意事項，功能同@remarks,顯示字樣不一樣
    /// @par    自定義圖塊，後面可跟示例代碼之類
    /// @code(必須使用@endcode結束)
    /// 示例代碼(無需縮進)    
    /// @endcode
    /// @see     其餘參考項【產生指向參考的連接】
    ///函數代碼聲明

8.特殊符號
    /// -        產生一個黑色圓點
9.定義在類體裏面的enum
  

 /// Camera types
    enum CAMERA_TYPE
    {
        CAMERA_FIRST_VIEW,/*!< Camera that looks from the first view */
        CAMERA_MODEL_VIEW,///< Camera that looks from the third view
    };

    兩種風格相同。如下開始的項都是全局非類內定義，在文件最開始(我嘗試是在include以前) 必須加上【/// \file 文件名】，不然不會生成註釋【沒有File Member頁】。10. 定義在文件裏面的宏     #define CAMERA_TYPE_NUMBER     ///< The number of camera types.       或     #define CAMERA_TYPE_NUMBER     /*!< The number of camera types. */    風格說明見5。11. 非類內enum定義同10.        兩種風格相同。見9。12. 非類內typedef定義同10.     風格說明見5。