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

時間 2019-11-07

標籤 doxygen 詳細介紹註釋風格简体版

原文原文鏈接

5 Doxygen的註釋風格

5.1 綜述

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

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

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

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

5.2 Doxygen支持的指令

5.2.1 概述

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

5.2.2 經常使用指令介紹

@file函數	檔案的批註說明。學習
@author測試	做者的信息spa
@brief.net	用於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中全部文件都清除再試。這個問題的緣由還不太肯定。