Doxygen詳細介紹（三）（Doxygen註釋風格）

5      Doxygen的註釋風格

5.1   綜述

在每一個代碼項中均可以有兩類描述, 這兩類描述將在文檔中格式化在一塊兒: 一種就是brief描述, 另外一種就是detailed。 兩種都是可選的，但不能同時沒有。

顧名思義, 簡述(brief)就是在一行內簡述地描述。而詳細描述(detailed description)則提供更長, 更詳細的文檔。

Doxygen支持c風格註釋、c++風格註釋以及javaDoc風格註釋等，下面將分別予以介紹。

若須要經過Doxygen生成漂亮的文檔，通常有以下幾個地方須要使用Doxygen支持的風格進行註釋：
    1） 文件頭（包括.h和.cpp）
        主要用於聲明版權，描述本文件實現的功能，以及文件版本信息等
    2） 類的定義
        主要用於描述該類的功能，同時也能夠包含使用方法或者注意事項的簡要描述
    3） 類的成員變量定義
        在類的成員變量上方，對該成員變量進行簡要地描述
    4） 類的成員函數定義
        在類定義的成員函數上方，對該成員函數功能進行簡要描述
    5） 函數的實如今函數的實現代碼處，詳細描述函數的功能、參數的含義、返回值的含義、使用本函數須要注意的問題、本函數使用其餘類或函數的說明等

 

5.2    Doxygen支持的指令

5.2.1   概述

能夠在註釋中加一些Doxygen支持的指令，主要做用是控制輸出文檔的排版格式，使用這些指令時須要在前面加上「\」或者「@」（JavaDoc風格）符號，告訴Doxygen這些是一些特殊的指令，經過加入這些指令以及配備相應的文字，能夠生成更加豐富的文檔，下面對比較經常使用的指令作一下簡單介紹。

5.2.2   經常使用指令介紹

@file	檔案的批註說明。
@author	做者的信息
@brief	用於class 或function的簡易說明 eg ： @brief 本函數負責打印錯誤信息串
@param	主要用於函數說明中，後面接參數的名字，而後再接關於該參數的說明
@return	描述該函數的返回值狀況 eg: @return 本函數返回執行結果，若成功則返回TRUE，不然返回FLASE
@retval	描述 返回值類型 eg: @retval NULL 空字符串。 @retval !NULL 非空字符串。
@ note	註解
@attention	注意
@ warning	警告信息
@enum	引用了某個枚舉，Doxygen會在該枚舉處產生一個連接 eg ： @enum CTest::MyEnum
@var	引用了某個變量，Doxygen會在該枚舉處產生一個連接 eg ： @var CTest::m_FileKey
@class	引用某個類， 格式：@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h"
@exception	可能產生的異常描述 eg: @exception 本函數執行可能會產生超出範圍的異常

 

5.3      JavaDoc風格的註釋

5.3.1    概述

JavaDoc 風格的註釋風格主要使用下面這種樣式： 即在註釋塊開始使用兩個星號 ‘ * ‘

 

/**   description
 *    description
 *    description
 */

5.3.2    簡述與詳述的方式

Doxygen 支持的塊（類、函數、結構體等）的註釋描述分爲兩種：簡述 和 詳述

通常註釋的描述由簡述開始，通過特殊分隔方式後，後面緊跟詳述的內容， javaDoc 風格可使用的分隔方法有如下兩種：

1）       使用 \brief 參數標識，空行做爲簡述和詳述的間隔標識

/*!    @brief  Brief description.
 *    description continued.
 *
 *    Detailed description starts here.
 */

2） 直接使用javaDoc風格，javaDoc風格自動以簡述開頭，以空行（或者小數點加空格）做爲簡述與詳述的分割

/**    Brief description
 *    description continued
 *
 *    Detailed description starts here.
 */

/**        Brief description
 *         description continued . (注意:這裏有一個小數點,加上一個空格)
 *         Detailed description starts here.
 */

5.3.3   文件頭註釋示例

5.3.4   類定義註釋示例

/**    本類的功能：打印錯誤信息
 *
 *     本類是一個單件
 *     在程序中須要進行錯誤信息打印的地方
 */
class CPrintError
{
            ……
}

5.3.5   類成員變量定義示例

（ 1 ）在成員變量上面加註釋的格式

/** 成員變量描述 */
int  m_Var;

（ 2 ）在成員變量後面加註釋的格式

int  m_color;     /**< 顏色變量 */

5.3.6   成員函數的註釋示例

/** 下面是一個含有兩個參數的函數的註釋說明（簡述）
 *
 *     這裏寫該函數的詳述信息
 *     @param a 被測試的變量（param描述參數）
 *     @param s 指向描述測試信息的字符串
 *     @return    測試結果 （return描述返回值）
 *     @see    Test()    （本函數參考其它的相關的函數，這裏做一個連接）
 *     @note    (note描述須要注意的問題)
 */
int testMe(int a,const char *s);

5.3.7     枚舉變量的註釋示例

/**    顏色的枚舉定義
  *
  *    該枚舉定義了系統中須要用到的顏色\n
  *    可使用該枚舉做爲系統中顏色的標識
  */
enum TEnum
{
     RED,           /**< 枚舉，標識紅色    */
     BLUE,          /**< 枚舉，標誌藍色    */
     YELLOW         /**< 枚舉，標誌×××. */
}enumVar;

5.4      C++風格的註釋

5.4.1    概述

C++ 的註釋風格主要使用下面這種樣式： 即在註釋塊開始使用三個反斜槓 ‘ / ’

其餘地方其實與 JavaDoc 的風格相似，只是 C++ 風格不用 「 * 」 罷了。

5.4.2       簡述與詳述

C++ 風格的簡述與詳述方式與 javaDoc 相似。

通常註釋的描述由簡述開始，通過特殊分隔方式後，後面緊跟詳述的內容， C++ 風格可使用的分隔方法有如下兩種：

（1） 使用 \brief 參數標識，空行做爲簡述和詳述的間隔標識

 

///    \brief  Brief description.
///    description continued.
///
///    Detailed description starts here.
///

（ 2 ） 使用以空行（或者小數點加空格）做爲簡述與詳述的分割

 

///   Brief description
///   description continued.
///
///   Detailed description starts here.

以小數點加空格做爲分隔以下：

///         Brief description
///         description continued . （注意:這裏有一個小數點,加上一個空格）
///         Detailed description starts here.
///

5.4.3    註釋風格約定

1. 一個代碼塊（類、函數、結構等）的概述採用單行的」///」加一個空格開頭的註釋，並寫在該代碼塊聲明的前面；
2. 一個代碼塊的詳述採用至少兩行的」///」加一個空格開頭的註釋，若不足兩行第二行的開頭也要寫出來，而且放在代碼塊定義的前面；若是某代碼沒有聲明只有定義或者相反，則在定義或者聲明前面寫上單行的概述+一個空行+多行的詳述；
3. 枚舉值列表的各項、結構域的各項等採用在本行最後添加」///<」加一個空格開頭的註釋；
4. 對變量的定義採用在變量上面加單行」///」加一個空格開頭的註釋（至關因而給改變量一個概述）；
5. 函數的參數用」/// @param」+一個空格開頭的行描述在函數的詳述裏面；
6. 函數的返回值用」/// @return」+一個空格開頭的行描述在函數的詳述裏面；
7. 函數之間的參考用」/// @see」+一個空格開頭的行描述在函數的詳述裏面；
8. 文件頭的版權以及文件描述的註釋參見例代碼。

5.4.4       文件頭註釋示例

5.4.5       類定義註釋示例

///    本類的功能：打印錯誤信息
///
///    本類是一個單件
///    在程序中須要進行錯誤信息打印的地方
class CPrintError
{
          ……
}

5.4.6       類成員變量定義示例

（ 1 ）在成員變量上面加註釋的格式

/// 成員變量描述
int  m_Var;

（ 2 ）在成員變量後面加註釋的格式

int  m_color;     /// 顏色變量

5.4.7       成員函數的註釋示例

/// 下面是一個含有兩個參數的函數的註釋說明（簡述）
///
///     這裏寫該函數的詳述信息
///     @param a 被測試的變量（param描述參數）
///     @param s 指向描述測試信息的字符串
///     @return    測試結果 （return描述返回值）
///     @see    Test()    （本函數參考其它的相關的函數，這裏做一個連接）
///     @note    (note描述須要注意的問題)
int testMe(int a,const char *s);

5.4.8       枚舉變量的註釋示例

 

///    顏色的枚舉定義
///
///    該枚舉定義了系統中須要用到的顏色\n
///    可使用該枚舉做爲系統中顏色的標識
enum TEnum
{
    RED,            ///< 枚舉，標識紅色
    BLUE,           ///< 枚舉，標誌藍色
    YELLOW          ///< 枚舉，標誌×××.
}enumVar;

5.5     須要注意的問題

（1）Doxygen會忽略你在註釋中加入的多餘的換行，若是你但願保留兩行註釋之間的空行，那麼，在該行加入 \n

 

6      Doxygen使用的常見問題小結

6.1     中文問題：中文註釋在文檔中是亂碼

解決：在expert中的INPUT選項頁的INPUT_ENCODEING中填入「GB2312」，這樣基於GB的文本編輯器生成的代碼就能夠正常使用了。

6.2    圖形問題：沒法繪製類圖協做圖等圖形。

解決：首先確保安裝了graphviz for win，注意不是wingraphviz，後者是一個graphviz的com封裝，可是doxygen並非基於它開發的，因此裝了也沒用。而後在expert的DOT_PATH中填入graphviz的安裝路徑。接着在wizard的diagram中選擇須要生成的圖形類別就能夠了。

若是出現沒法包含.map文件的錯誤，能夠將工做目錄設置成html，並將html中全部文件都清除再試。這個問題的緣由還不太肯定。

6.3    輸出chm的問題：如何輸出.chm文件

配置時注意expert中的HTML頁：選中「GENERATE_HTMLHELP」，而後在CHM_FILE中填上想要的chm文件名。

HHC_LOCATION中輸入hhc.exe文件的路徑。hhc.exe能夠經過安裝HTML Help Workshop得到。

或者使用HTML Help Workshop來編譯Doxygen生成的html文件夾中的.hhp文件，編譯完成後便可在該html文件夾中找到對應的chm文件

6.4     Doxygen沒法爲DLL中定義的類 導出文檔

例如：

class __declspec(dllexport) CClassName:public CObject

{

}

目前發現Doxygen沒法識別出DLL中定義的類。

7.  感謝

最後，感謝您的閱讀，若是您對此有什麼建議或者意見，歡迎在本博客上留言，也能夠E-mail 至 lujun.hust@gmail.com