參考：
1.https://blog.csdn.net/liao20081228/article/details/77322584
2.https://blog.csdn.net/wang15061955806/article/details/50978195 （有詳細格式）
版權聲明：本文章轉載自Jhuster的《Doxygen詳細介紹》。未經作者允許，嚴禁用於商業出版，否則追究法律責任。網絡轉載請注明出處，這是對原創者的起碼的尊重！！！
1 簡介
為代碼寫注釋一直是大多數程序員有些困擾的事情。更頭痛的是寫文檔，以及維護文檔的問題，而doxygen就能把遵守某種格式的注釋自動轉化為對應的文檔。 Doxygen是基於GPL的開源項目，是一個非常優秀的文檔系統，當前支持在大多數unix（包括linux），windows家族，Mac系統上運行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）語言，部分支持PHP和C#語言，輸出格式包括HTML、latex、RTF、ps、PDF、壓縮的HTML和unix manpage。有很多開源項目（如log4cpp和CppUnit）都使用了doxygen文檔系統。
2 Doxygen配置文件
2.1 生成Doxygen配置文件
運行Doxywizard創建配置文件。可以直接點“Save…”按鈕，將保存默認的配置文件，名為Doxyfile，內容是Doxygen的默認設置。Doxyfile是普通文本文件，可以直接打開手動編輯。不過在Doxywizard的界面上填寫也很方便，每個參數都有詳細提示。建議用Doxywizard完成第一次設置。以后如果需要調整個別參數，可以直接編Doxyfile。 上述Doxywizard界面中提供了生成Doxygen文檔的4個步驟，按照上述步驟一步步執行就可以生成漂亮的文檔了。 第一步是生成配置文件，提供三種方式：
- Wizard方式指簡約方式，在其中只提供一些重要的參數設置，其余的均為默認值；
- Expert方式為詳細設置方式，通過該選項可以詳細地配置Doxygen的各個配置項；
- Load方式，用於導入以前生成的Doxygen配置文件，導入后可以再點擊Expert進行修改。
2.2 配置選項含義詳解
| 選項 | 含義 |
|---|---|
| DOXYFILE_ENCODING | Doxygen文件的編碼方式，默認為UTF-8，若希望支持中文，最好設置為 GB2312 |
| PROJECT_NAME | Project 的名字，以一個單詞為主，多個單詞請使用雙引號括住。 |
| PROJECT_VERSION | Project的版本號碼。 |
| OUTPUT_DIRECTORY | 輸出路徑。產生的文件會放在這個路徑之下。如果沒有填這個路徑，將會以目前所在路徑作為輸出路徑。 |
| OUTPUT_LANGUAGE | 輸出語言, 默認為English 。 |
| EXTRACT_ALL | 為NO，只解釋有doxygen格式注釋的代碼；為YES，解析所有代碼，即使沒有注釋 |
| EXTRACT_PRIVATE | 是否解析類的私有成員 |
| EXTRACT_STATIC | 是否解析靜態項 |
| EXTRACT_LOCAL_CLASSES | 是否解析源文件（cpp文件）中定義的類 |
| INPUT | 指定加載或找尋要處理的程序代碼文件路徑。這邊是一個表列式的型態。並且可指定檔案及路徑。 |
| FILE_PATTERNS | 如果您的INPUT Tag 中指定了目錄。您可以透過這個Tag來要求Doxygen在處理時，只針對特定的檔案進行動作。例如：您希望對目錄下的擴展名為.c, .cpp及.h的檔案作處理。您可設定FILE_PATTERNS = .c, .cpp, *.h。 |
| RECURSIVE | 這是一個布爾值的Tag，只接受YES或NO。當設定為YES時，INPUT所指定目錄的所有子目錄都會被處理. |
| EXCLUDE | 如果您有某幾個特定檔案或是目錄，不希望經過Doxygen處理。您可在這個Tag中指定。 |
| EXCLUDE_PATTERNS | 類似於FILE_PATTERNS的用法，只是這個Tag是供EXCLUDE所使用。 |
| SOURCE_BROWSER | 如果設定為YES，則Doxygen會產生出源文件的列表，以供查閱。 |
| INLINE_SOURCES | 如果設定為YES ，則函數和類的實現代碼被包含在文檔中 |
| ALPHABETICAL_INDEX | 如果設定為YES，則一個依照字母排序的列表會加入在產生的文件中。（有很多類、結構等項時建議設為YES） |
| GENERATE_HTML | 若設定為YES ，就會產生HTML版本的說明文件。HTML文件是Doxygen預設產生的格式之一。 |
| HTML_OUTPUT | HTML文件的輸出目錄。這是一個相對路徑，所以實際的路徑為OUTPUT_DIRECTORY加上HTML_OUTPUT。這個設定預設為html。 |
| GENERATE_HTMLHELP | 是否生成壓縮HTML格式文檔（.chm） |
| HTML_FILE_EXTENSION | HTML文件的擴展名。預設為.html。 |
| HTML_HEADER | 要使用在每一頁HTML文件中的Header。如果沒有指定，Doxygen會使用自己預設的Header。 |
| HTML_FOOTER | 要使用在每一頁HTML文件中的Footer。如果沒有指定，Doxygen會使用自己預設的Footer。 |
| HTML_STYLESHEET | 您可給定一個CSS 的設定，讓HTML的輸出結果更完美。 |
| GENERATE_HTMLHELP | 如設定為YES，Doxygen會產生一個索引文件。這個索引文件在您需要制作windows 上的HTML格式的HELP檔案時會用的上。 |
| GENERATE_TREEVIEW | 若設定為YES，Doxygen會幫您產生一個樹狀結構，在畫面左側。這個樹狀結構是以JavaScript所寫成。所以需要新版的Browser才能正確顯示。 |
| TREEVIEW_WIDTH | 用來設定樹狀結構在畫面上的寬度。 |
| GENERATE_LATEX | 設定為YES 時，會產生LaTeX 的文件。不過您的系統必需要有安裝LaTeX 的相關工具。 |
| LATEX_OUTPUT | LaTeX文件的輸出目錄，與HTML_OUTPUT用法相同，一樣是指在OUTPUT_DIRECTORY之下的路徑。預設為latex。 |
| LATEX_CMD_NAME | LaTeX程序的命令名稱及檔案所在。預設為latex。 |
| GENERATE_RTF | 若設定為YES ，則會產生RTF 格式的說明檔。 |
| RTF_OUTPUT | 與HTML_OUTPUT 用法相同，用來指定RTF 輸出檔案路徑。預設為rtf。 |
| GENERATE_MAN | 若設定為YES ，則會產生Unix Man Page 格式的說明文件。 |
| MAN_OUTPUT | 與HTML_OUTPUT 用法相同，用來指定Man Page的輸出目錄。預設為man。 |
| GENERATE_XML | 若設定為YES ，則會產生XML 格式的說明文件。 |
| ENABLE_PREPROCESSING | 若設定為YES ，則Doxygen 會激活C 的前置處理器來處理原始檔。 |
| PREDEFINED | 可以讓您自行定義一些宏。類似於gcc 中的-D選項。 |
| CLASS_DIAGRAMS | 這個標記用來生成類繼承層次結構圖。要想生成更好的視圖，可以從 Graphviz 下載站點 下載 dot 工具。Doxyfile 中的以下標記用來生成圖表： |
| HAVE_DOT | 如果這個標記設置為 Yes，doxygen 就使用 dot 工具生成更強大的圖形，比如幫助理解類成員及其數據結構的協作圖。注意，如果這個標記設置為 Yes， 標記就無效了 |
| CLASS_GRAPH | 如果 標記和這個標記同時設置為 Yes，就使用 dot 生成繼承層次結構圖 |
| GRAPHICAL_HIERARCHY | 設置為YES時，將會繪制一個圖形表示的類圖結構 |
3 Doxygen的注釋風格
3.1 綜述
在每個代碼項中都可以有兩類描述, 這兩類描述將在文檔中格式化在一起: brief描述和detailed。 兩種都是可選的，但不能同時沒有。,簡述(brief)就是在一行內簡述地描述。而詳細描述(detailed description)則提供更長, 更詳細的文檔。 Doxygen支持c風格注釋、c++風格注釋以及javaDoc風格注釋等，下面將分別予以介紹。 若需要通過Doxygen生成漂亮的文檔，一般有如下幾個地方需要使用Doxygen支持的風格進行注釋：
- 文件頭（包括.h和.cpp） 主要用於聲明版權，描述本文件實現的功能，以及文件版本信息等
- 類的定義 主要用於描述該類的功能，同時也可以包含使用方法或者注意事項的簡要描述
- 類的成員變量定義 在類的成員變量上方，對該成員變量進行簡要地描述
- 類的成員函數定義 在類定義的成員函數上方，對該成員函數功能進行簡要描述
- 函數的實現在函數的實現代碼處，詳細描述函數的功能、參數的含義、返回值的含義、使用本函數需要注意的問題、本函數使用其他類或函數的說明等
3.2 Doxygen支持的指令
可以在注釋中加一些Doxygen支持的指令，主要作用是控制輸出文檔的排版格式，使用這些指令時需要在前面加上“\”或者“@”（JavaDoc風格）符號，告訴Doxygen這些是一些特殊的指令，通過加入這些指令以及配備相應的文字，可以生成更加豐富的文檔，下面對比較常用的指令做一下簡單介紹。
| 指令 | 說明 |
|---|---|
| @file | 檔案的批注說明。 |
| @author | 作者的信息 |
| @brief | 用於class 或function的簡易說明eg：@brief 本函數負責打印錯誤信息串 |
| @param | 主要用於函數說明中，后面接參數的名字，然后再接關於該參數的說明 |
| @return | 描述該函數的返回值情況eg:@return 本函數返回執行結果，若成功則返回TRUE，否則返回FLASE |
| @retval | 描述返回值類型，eg:@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 本函數執行可能會產生超出范圍的異常 |
3.3 JavaDoc風格的注釋
3.3.1 概述
JavaDoc風格的注釋風格主要使用下面這種樣式：即在注釋塊開始使用兩個星號‘*‘
/** description * description * description */ - 1
- 2
- 3
- 4
3.3.2 簡述與詳述的方式
Doxygen支持的塊（類、函數、結構體等）的注釋描述分為兩種：簡述 和 詳述。一般注釋的描述由簡述開始，經過特殊分隔方式后，后面緊跟詳述的內容，javaDoc風格可以使用的分隔方法有以下兩種：
- 使用 \brief 參數標識，空行作為簡述和詳述的間隔標識
/*! @brief Brief description. * description continued. * * Detailed description starts here. */ - 1
- 2
- 3
- 4
- 5
- 直接使用javaDoc風格，javaDoc風格自動以簡述開頭，以空行（或者小數點加空格）作為簡述與詳述的分割
/** Brief description * description continued * * Detailed description starts here. */ /** Brief description * description continued . (注意:這里有一個小數點,加上一個空格) * Detailed description starts here. */ - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
3.3.3 文件頭注釋示例
3.3.4 類定義注釋示例
/** 本類的功能：打印錯誤信息 * * 本類是一個單件 * 在程序中需要進行錯誤信息打印的地方 */ class CPrintError { …… } - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
3.3.5 類成員變量定義示例
- 在成員變量上面加注釋的格式
/** 成員變量描述 */ int m_Var; - 1
- 2
- 在成員變量后面加注釋的格式
int m_color; /**< 顏色變量 */ - 1
3.3.6 成員函數的注釋示例
/** 下面是一個含有兩個參數的函數的注釋說明（簡述） * * 這里寫該函數的詳述信息 * @param a 被測試的變量（param描述參數） * @param s 指向描述測試信息的字符串 * @return 測試結果 （return描述返回值） * @see Test() （本函數參考其它的相關的函數，這里作一個鏈接） * @note (note描述需要注意的問題) */ int testMe(int a,const char *s); - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
3.3.7 枚舉變量的注釋示例
/** 顏色的枚舉定義 * * 該枚舉定義了系統中需要用到的顏色\n * 可以使用該枚舉作為系統中顏色的標識 */ enum TEnum { RED, /**< 枚舉，標識紅色 */ BLUE, /**< 枚舉，標志藍色 */ YELLOW /**< 枚舉，標志黃色. */ }enumVar; - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
3.4 C++風格的注釋
3.4.1 概述
C++的注釋風格主要使用下面這種樣式：即在注釋塊開始使用三個反斜杠‘/’其他地方其實與JavaDoc的風格類似，只是C++風格不用 “*” 罷了。
3.4.2 簡述與詳述
C++風格的簡述與詳述方式與javaDoc類似。 一般注釋的描述由簡述開始，經過特殊分隔方式后，后面緊跟詳述的內容，C++風格可以使用的分隔方法有以下兩種： * 使用 \brief 參數標識，空行作為簡述和詳述的間隔標識
/// \brief Brief description. /// description continued. /// /// Detailed description starts here. /// - 1
- 2
- 3
- 4
- 5
- 使用以空行作為簡述與詳述的分割
/// Brief description /// description continued. /// /// Detailed description starts here. - 1
- 2
- 3
- 4
- 以小數點加空格作為分隔如下：
/// Brief description /// description continued . （注意:這里有一個小數點,加上一個空格） /// Detailed description starts here. /// - 1
- 2
- 3
- 4
3.4.3 注釋風格約定
- 一個代碼塊（類、函數、結構等）的概述采用單行的”///”加一個空格開頭的注釋，並寫在該代碼塊聲明的前面；
- 一個代碼塊的詳述采用至少兩行的”///”加一個空格開頭的注釋，若不足兩行第二行的開頭也要寫出來，並且放在代碼塊定義的前面；如果某代碼沒有聲明只有定義或者相反，則在定義或者聲明前面寫上單行的概述+一個空行+多行的詳述；
- 枚舉值列表的各項、結構域的各項等采用在本行最后添加”///<”加一個空格開頭的注釋；
- 對變量的定義采用在變量上面加單行”///”加一個空格開頭的注釋（相當於是給改變量一個概述）；
- 函數的參數用”/// @param”+一個空格開頭的行描述在函數的詳述里面；
- 函數的返回值用”/// @return”+一個空格開頭的行描述在函數的詳述里面；
- 函數之間的參考用”/// @see”+一個空格開頭的行描述在函數的詳述里面；
- 文件頭的版權以及文件描述的注釋參見例代碼。
3.4.4 文件頭注釋示例
3.4.5 類定義注釋示例
/// 本類的功能：打印錯誤信息 /// /// 本類是一個單件 /// 在程序中需要進行錯誤信息打印的地方 class CPrintError { …… } - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
3.4.6 類成員變量定義示例
*在成員變量上面加注釋的格式
/// 成員變量描述 int m_Var; - 1
- 2
*在成員變量后面加注釋的格式
int m_color; /// 顏色變量 - 1
3.4.7 成員函數的注釋示例
/// 下面是一個含有兩個參數的函數的注釋說明（簡述） /// /// 這里寫該函數的詳述信息 /// @param a 被測試的變量（param描述參數） /// @param s 指向描述測試信息的字符串 /// @return 測試結果 （return描述返回值） /// @see Test() （本函數參考其它的相關的函數，這里作一個鏈接） /// @note (note描述需要注意的問題) int testMe(int a,const char *s); - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
3.4.8 枚舉變量的注釋示例
/// 顏色的枚舉定義 /// /// 該枚舉定義了系統中需要用到的顏色\n /// 可以使用該枚舉作為系統中顏色的標識 enum TEnum { RED, ///< 枚舉，標識紅色 BLUE, ///< 枚舉，標志藍色 YELLOW ///< 枚舉，標志黃色. }enumVar; - 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
3.5 需要注意的問題
- Doxygen會忽略你在注釋中加入的多余的換行，如果你希望保留兩行注釋之間的空行，那么，在該行加入 \n
4 常見問題
4.1 中文問題：中文注釋在文檔中是亂碼
解決：在expert中的INPUT選項頁的INPUT_ENCODEING中填入“GB2312”，這樣基於GB的文本編輯器生成的代碼就可以正常使用了。
4.2 圖形問題：無法繪制類圖協作圖等圖形。
解決：首先確保安裝了graphviz for win，注意不是wingraphviz，后者是一個graphviz的com封裝，但是doxygen並不是基於它開發的，所以裝了也沒用。然后在expert的DOT_PATH中填入graphviz的安裝路徑。接着在wizard的diagram中選擇需要生成的圖形類別就可以了。 如果出現無法包含.map文件的錯誤，可以將工作目錄設置成html，並將html中所有文件都清除再試。這個問題的原因還不太確定。
4.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文件
4.4 Doxygen無法為DLL中定義的類 導出文檔
例如：
class __declspec(dllexport) CClassName:public CObject { } 目前發現Doxygen無法識別出DLL中定義的類。- 1
- 2
- 3
- 4
- 5
版權聲明：本文章轉載自Jhuster的《Doxygen詳細介紹》。未經作者允許，嚴禁用於商業出版，否則追究法律責任。網絡轉載請注明出處，這是對原創者的起碼的尊重！！！