前言
下面主要講解linux下Doxygen命令行實現html文檔生成的操作，當然也有界面版本操作方式，linux下安裝doxygen-gui即可通過doxywizard開啟界面操作，windows下也可以通過doxywizard.exe界面進行配置操作，具體的界面操作請參考其他網上文章，不過有一句話需要說明：會命令行操作的，應該都會界面操作，而會界面操作的就不一定會命令行操作了。
windows下的操作方式可以參考 使用doxygen生成chm范例
doxygen是什么
按照約定的格式注釋源代碼，用工具處理注釋過的源代碼產生文檔。通過這種方式產生文檔至少有以下好處：
- 便於代碼和文檔保持同步
- 可以對文檔做版本管理
Doxygen就是這樣的工具，Doxygen是一個程序的文件產生工具，可將程序中的特定批注轉換成為說明文件。很多編程語言都有類似的文檔工具，例如：Java有javadoc，Ruby有rdoc。對於C/C++程序，我們可以用Doxygen生成文檔。Doxygen有如下特點：
- 支持的編程語言：完全支持 C、C++、Java、IDL、Objective-C、Python、PHP、C#、Fortran、VHDL
- 輸出格式：直接支持 HTML、Latex、RTF、manpage、Qt help project、XML，間接支持 chm、
Qt Compressed Help、Postcript和PDF； - 兼容 JavaDoc、Qt-Doc、KDOC等類似工具；
- 支持平台：Unix（包括Linux）、MacOs、Windows等；
主頁：http://www.doxygen.org/
郵件列表：
doxygen-user@lists.sourceforge.net
doxygen-develop@lists.sourceforge.net
作者：Dimitri van Heesch (dimitri@stack.nl) ；
Doxygen基本操作流程
- 按照Doxygen的約定，將代碼“文檔化”。這部分請參考 代碼‘文檔化’；
- 編寫一個配置文件（Doxyfile），用於配合Doxygen生成最終的文檔。這部分請參考 編寫一個Doxygen配置文件；
- 執行doxygen Doxyfile生成文檔。
下面詳細介紹每一個步驟。
代碼‘文檔化’
這一部分需要了解基本的注釋規則和doxygen注釋標記
doxygen注釋規則
並非所有程序代碼中的注釋都會被 Doxygen 處理(除非在配置文件里使能了EXTRACT_ALL等選項)，必需依照正確的格式撰寫，Doxygen 可處理下面兩種類型的注解(注意：默認采用的JavaDoc風格，你也可以選擇采用Qt或者c/c++風格),如下:
/**
* ...多行注釋...
*
*/
/** ...單行注釋... */
由於 Doxygen 認為注釋是說明它下面的程序代碼。所以,如果注釋要與前面的程序碼在同一行內,則需用下面這種型式的注釋:
/**< ...代碼同行情況的注釋 */
注意,除**后多了一個<,其它的與前面相同。
首先,我們先說明在 Doxygen 中對於類別或是函數注解的一個特定格式。
/**
*
* struct、class、functiond的簡易說明...
*
* struct、class、functiond的詳細說明...
* ...
*/
上面這個例子要說的是,在 Doxygen 處理一個類定義或是函數定義之上的注釋時:
會先判斷第一行為簡易說明,這個簡易說明將一直到遇見一個空白行的出現或是遇到第一個 . 為止;
之后的注解將會被視為詳細說明。
另一種比較清楚的方式是指定@brief 的指令,這將會明確的告訴 Doxygen 哪個是簡易說明。
doxygen在處理注釋文檔的時候，會進行如下的過程：
- 執行在文檔中的特殊命令。命令都以''或'@'開始,二者是一樣的，都是為了引出一個命令。例如'\brief','\details','@brief', '@details'等等。
- 如果一行以空白開始，后面跟着一個或者多個''，然后又跟着0個或者多個空白，那么所有的空白和''將會被移除。
- 所有的空行將會被當作段分隔符號。
- 為相應的被文檔化了的類的單詞創建相應的鏈接（除非這個單詞前面放置一個'%'，這時候就沒有鏈接了並且'%'也會被移走了）。
- 如果在文本中發現了相應的匹配，會建立成員的鏈接。(?)
- 文檔中的HTML標記會被解釋、轉化為LATEX的東西以便成為LATEX的輸出。(?)
Doxygen常用的代碼注釋標記
- 文件信息
@file 文件名(遵守文件命名規則) --> 文件聲明，即當前文件名
@author 作者名 --> 作者
@version 版本號 --> 版本號
@todo 說明文字 --> TODO 列表，在相關頁面有它專門一項
注:只能在實現文件(.c/.cpp)中使用，如果相同函數的實現文件與頭文件中均有，生成的文檔中會有重復項，可以理解為調用者不應知道實現流程
@date 日期時間 --> 說明文件生成的日期時間
@section 章節標題 --> @section LICENSE 版權許可 @section DESCRIPTION 描述 - 模塊信息
@defgroup 模塊名(英文) 顯示名(中文) @{ 類/函數/變量/宏/... @}--> 定義模塊
@ingroup 模塊名(英文) [顯示名(中文)]--> 作為指定名的模塊的子模塊,顯示名為可選項,可與指定名的模塊的顯示名不同
@addtogroup 模塊名(英文) [顯示名(中文)] --> 作為指定名的模塊的成員,顯示名為可選項,必需與指定名的模塊的顯示名相同
@name 顯示名(中文) @{ 變量/宏 @} --> 按用途分,以便理解全局變量/宏的用途
這部分推薦參考： doxygen使用總結 - 函數信息
@param 參數名 說明文字 --> 不建議使用這個
@param[in] 參數名 說明文字 --> 輸入參數
@param[out] 參數名 說明文字 --> 輸出參數
@param[in,out] 參數名 說明文字 --> 即輸入又輸出參數
@exception 用來說明異常類及拋出條件
@remark 表示評論，暴露給客戶程序員的文檔
@return 說明文字 --> 返回值說明
@retval 說明文字 --> 特定返回值說明
@note 說明文字 --> 注解,可以描述工作流程和注意事項
@par [段落標題] --> 開創新段落,一般與示例代碼聯用
@code --> 示例代碼開始
@endcode --> 示例代碼結束
@see 類/函數/變量/文件/URL --> 參見,
類名::函數名 或 ::函數名 可以變成超鏈接點擊跳轉到對應函數說明處
函數重載的情況下,要帶上參數列表以及返回值
@deprecated 說明文字 --> 過時列表,在相關頁面有它專門一項
注:只能在頭文件(*.h)中使用,如果相同函數的實現文件與頭文件中均有,
生成的文檔中會有重復項,可以理解為維護者不關心這個接口是不是要過時
@pre 說明文字 --> 前置條件
@arg 參數/返回值 說明文字 --> 以列表形式說明參數取值意義
注:也可以用 - 或 -# 來代替,建議此種方法,簡單明了
- 第一級
- 第二級
- 第三級
即相同開頭的-或-#第二行比第一行縮進一個英文空格就變了第二級,依次類推
-開頭的第一級為實心黑圓點;第二級為空心黑圓點;第三級以后為實心方塊;
-#開頭的第一級為數字(1./2./3./...),
第二級為小寫字母(a./b./c./...),
第三級為羅馬數字(i./ii./iii./...),
第四級為大寫字母(A./B./C./...) - 提醒信息
@brief 說明文字 --> 摘要,即當前文件/函數說明
@attention 說明文字 --> 注意
@bug 說明文字 --> 問題
@warning 說明文字 --> 警告
@ref 引用其他標記，類似於html中的錨
@since {text} 通常用來說明從什么版本、時間寫此部分代碼
@relates通常用做把非成員函數的注釋文檔包含在類的說明文檔中
@def 宏定義說明
@fn 函數 函數說明
@test 測試示例、信息
(@bug、@test以及@todo等會出現鏈接頁面)
下面為生成特殊字體的命令：
@a @e @em：其后的單個字(word)表現為斜體，以強調作用。如有多個word的話，使用xxx xxx代替
@b：其后的word為粗體，多個則使用xxx xxx
@c @p：字體表現為打印機字體，多個則使用xxx xxx
@enum 引用了某個枚舉，Doxygen會在該枚舉處產生一個鏈接 eg：@enum CTest::MyEnum
@var 引用了某個變量，Doxygen會在該枚舉處產生一個鏈接 eg：@var CTest::m_FileKey
@class 引用某個類，格式：@class
下面舉例說明可能遇到的幾種情況：
- 文件注釋
/**
* @file
* @author rongp
* @version 1.0.0
* @date 2016/02/22
*
* @section LICENSE
*
* Copyright(c) 2015-2020 XXX
* All rights reserved
*
* @brief iss服務器端sdk導出根文件
*
* @section DESCRIPTION
* 界面開發者只需要包含該頭文件即可, 具體的導出數據結構、api分別分別在
* net_io_export.h和app_amp_export.h中
*
*/
- 函數注釋
/**
* @brief 創建與本地服務通訊的端點
* @param[in] proto_type 端點通訊采用的協議類型, 一般設置為PROTO_TYPE_TRANS即可
*
* @return 用於通訊的端點指針，作為后面接口的參數
* @retval non-NULL 成功
* @retval NULL 出錯
*
* @warning 該接口只能在服務端sdk使用, 當前只支持PROTO_TYPE_TRANS協議類型
*
* 示例
@code
gpointer e = net_io_create_local_endpoint(PROTO_TYPE_TRANS);
@endcode
*
* @since 1.0.0
*/
- 結構體注釋
/**
* @brief 服務器信息描述結構
*/
struct _ServerInfo {
/** 服務器系統版本, 包括硬件信息、操作系統信息等 */
gchar sys_ver[128];
/** 服務器軟件版本 */
gchar soft_ver[128];
};
- 枚舉注釋
/**
* @brief 消息返回碼
*/
enum MSG_RET_CODE {
/** 執行成功 */
MSG_EXECUTE_OK = 0,
/** 超時 */
MSG_TIMEOUT = -1,
/** 消息的大小有誤 */
MSG_SIZE_UNMATCH = -2,
/** 不允許執行該消息 */
MSG_OPT_FORBID = -3,
/** 服務器端服務出錯 */
MSG_SYSTEM_ERR = -4,
/** 消息的參數有誤 */
MSG_ARG_INVALID = -5,
/** buf內存不夠 */
MSG_NOMEM = -100,
};
編寫一個Doxygen配置文件
一般是通過先生成模板配置文件，然后基於模板配置文件修改即可。使用 "doxygen -g" 命令在當前目錄下生成名為‘Doxyfile’的配置文件模板。也可以采用 "doxygen -g filename" 命令格式指定所生成的配置文件名為filename。如無特殊需要，采用默認的配置文件名即可。如果對 Doxygen 各配置選項的意義有一定了解，可以在生成配置文件的命令中添加 "-s" 選項，生成不含注釋的配置文件，如:doxygen -s -g 這種方式生成的配置文件非常精簡，沒有任何注釋。
有了doxygen模板配置文件后，現在要做的就是對它進行修改了，下面以c語言開發的項目生成html為例。主要有下面幾個選項需要修改：
# 項目名稱，將作為於所生成的程序文檔首頁標題，需要使用雙引號括住
PROJECT_NAME = “xxx”
# 文檔版本號，可對應於項目版本號，譬如 git、svn、cvs 所生成的項目版本號
PROJECT_NUMBER = “1.0.0”
# 程序文檔輸出目錄，產生的文件會放在這個路徑之下。如果沒有填這個路徑，將會以當前所在路徑來作為輸出路徑。
OUTPUT_DIRECTORY = doc/
# 程序文檔語言環境，預設為 English。1.2.16 版后，可以用 Chinese 輸出簡體中文，也可以使用
# Chinese-Traditional 來輸出中文繁體的格式。
OUTPUT_LANGUAGE = Chinese
# 如果是制作 C 程序文檔，該選項必須設為YES，否則默認生成 C++ 文檔格式
OPTIMIZE_OUTPUT_FOR_C = YES
# 對於使用 typedef 定義的結構體、枚舉、聯合等數據類型，只按照 typedef 定義的類型名進行文檔化
TYPEDEF_HIDES_STRUCT = YES
# 把這個標記設置為Yes，即使各個類或函數沒有文檔，也要提取信息
EXTRACT_ALL = YES
# 把這個標記設置為Yes，文檔就會包含類的私有數據成員
EXTRACT_PRIVATE = YES
# 把這個標記設置為Yes，文檔就會包含文件的靜態成員(函數和變量)
EXTRACT_STATIC = YES
# 在 C++ 程序文檔中,該值可以設置為 NO，而在 C 程序文檔中，由於 C 語言沒有所謂的域/名字空間
# 這樣的概念，所以此處設置為 YES
HIDE_SCOPE_NAMES = YES
# 讓 doxygen 靜悄悄地為你生成文檔，只有出現警告或錯誤時，才在終端輸出提示信息
QUIET = YES
# 這個標記創建一個以空格分隔的所有目錄的列表，
# 這個列表包含需要生成文檔的 C/C++ 源代碼文件和頭文件，可以不設定，即為當前目錄!
INPUT = inc/
# 輸入文件的編碼格式，需要自己根據INPUT指定的文件選擇，否則會亂碼
INPUT_ENCODING = UTF-8
# 在默認情況下,doxygen 會搜索具有典型 C/C++ 擴展名的文件，
# 比如 .c、.cc、.cpp、.h 和 .hpp 。
# 可以使用如下形式的列表方式,指定INPUT下要處理的文件
# 注:文件類型后有空格然后是右斜杠然后回車,每一個文件類均獨自一行!
# FILE_PATTERNS = *.h \
*.c \
*.cpp
FILE_PATTERNS =
# 遞歸遍歷由 INPUT 所指定的目錄及其所有子目錄，尋找由 FILE_PATTERNS 指定的要被文檔化的文件
RECURSIVE = YES
# 如果您有特定文件或目錄，不希望經過 Doxygen 處理，那你可在這指出，沒有就不指出
# 例如:EXCLUDE = /home/xxx/src_root /home/xxx/test
EXCLUDE =
# 類似於 FILE_PATTERNS 的用法，只是這個是供 EXCLUDE 所使用
EXCLUDE_PATTERNS =
# 若設定為 YES，就會產生 HTML 版本的說明文件。HTML 文件是 Doxygen 預設產生的格式之一
GENERATE_HTML = YES
# 若設定為 YES，Doxygen 會幫您產生一個樹狀結構，在頁面左側，默認為 NO
# 這個樹狀結構是以 JavaScript 所寫成。所以需要新版的 Browser 才能正確顯示。
GENERATE_TREEVIEW = YES
其他可參考的：
文檔輸出格式
除了 HTML 之外，doxygen 還可以生成幾種輸出格式的文檔。可以讓 doxygen 生成以下格式的文檔：
UNIX 手冊頁：把 <GENERATE_MAN> 標記設置為 Yes。在默認情況下，會在 <OUTPUT_DIRECTORY> 指定的目錄中創建 man 子文件夾，生成的文檔放在這個文件夾中。必須把這個文件夾添加到 MANPATH 環境變量中。
Rich Text Format（RTF）：把 <GENERATE_RTF> 標記設置為 Yes。把 <RTF_OUTPUT> 標記設置為希望放置 .rtf 文件的目錄；在默認情況下，文檔放在 OUTPUT_DIRECTORY 中的 rtf 子文件夾中。要想支持跨文檔瀏覽，應該把 <RTF_HYPERLINKS> 標記設置為 Yes。如果設置這個標記，生成的 .rtf 文件會包含跨文檔鏈接。
Latex：在默認情況下，doxygen 生成 Latex 和 HTML 格式的文檔。在默認的 Doxyfile 中，<GENERATE_LATEX> 標記設置為 Yes。另外，<LATEX_OUTPUT> 標記設置為 Latex，這意味着會在 OUTPUT_DIRECTORY 中創建 latex 子文件夾並在其中生成 Latex 文件。
Microsoft® Compiled HTML Help（CHM）格式：把 <GENERATE_HTMLHELP> 標記設置為 Yes。因為在 UNIX 平台上不支持這種格式，doxygen 只在保存 HTML 文件的文件夾中生成一個 index.hhp 文件。您必須通過 HTML 幫助編譯器把這個文件轉換為 .chm 文件。
Extensible Markup Language（XML）格式：把 <GENERATE_XML> 標記設置為 Yes。（注意，doxygen 開發團隊還在開發 XML 輸出）。
按照上面的修改后，就可以執行第三步，執行命令doxygen Doxyfile生成文檔了。注意：這里的Doxyfile
為你實際的Doxygen配置文件名。
Doxygen與其他工具配合生成chm
參考 https://stackoverflow.com/questions/23680921/generate-chm-from-doxgen-results
Doxygen FAQ
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中定義的類。
http://ticktick.blog.51cto.com/823160/188674
參考：
學習用 doxygen 生成源碼文檔
Doxygen使用指南 - Doxygen_Using_Manual.pdf
Doxygen: Main Page
Doxygen Manual: Getting started
未完，待續
2016年6月