簡介
- Doxygen 是一個將文件的特定注釋轉化為文檔的工具
- Doxygen 默認支持的語言有：C，C++，C#，Objective-C，IDL，Java，VHDL，PHP，Python，Tcl，Fortran 和 D
測試環境
- Ubuntu 18.04 LTS
- Doxygen 1.8.13
- C++
安裝
$ sudo apt install graphviz
$ sudo apt install doxygen
使用
1. 生成配置文件
- 默認配置文件名為：Doxyfile
$ doxygen -g <config-file>
- 或（不含注釋）
$ doxygen -s -g <config-file>
2. 修改配置文件
常用配置選項如下：
- 項目的編碼，默認為 UTF-8
DOXYFILE_ENCODING = UTF-8
- 項目的名稱
PROJECT_NAME = "project-name"
- 項目的版本號
PROJECT_NUMBER = "1.0.0"
- 項目的描述
PROJECT_BRIEF = "這是項目描述"
- 項目的 logo
PROJECT_LOGO = ""
- 需要處理的輸入目錄，如果未設置，則在當前目錄查找
INPUT = src
- 需要匹配的輸入文件
FILE_PATTERNS = *.cc *.h
- 不需要處理的輸入目錄
EXCLUDE =
- 不需要匹配的輸入文件
EXCLUDE_PATTERNS =
- 輸入編碼，默認為 UTF-8
INPUT_ENCODING = UTF-8
- 是否遞歸搜索輸入目錄，默認為 NO
RECURSIVE = NO
- 是否提取所有類，函數等（不包括類的私有成員和靜態成員），默認為 NO
EXTRACT_ALL = NO
- 是否提取類的私有成員，默認為 NO
EXTRACT_PRIVATE = NO
- 是否提取類的靜態成員，默認為 NO
EXTRACT_STATIC = NO
- 文檔是否包含源文件，默認為 NO
SOURCE_BROWSER = NO
- 是否對每個類都鏈接其所在的頭文件中，默認值為 YES
VERBATIM_HEADERS = YES
- 文檔的輸出目錄，如果未設置，輸出到當前目錄
OUTPUT_DIRECTORY = doc
- 是否支持 Markdown，默認值為 YES
MARKDOWN_SUPPORT = YES
- 文檔的主界面
USE_MDFILE_AS_MAINPAGE = README.md
- 文檔的語言，默認為 English
OUTPUT_LANGUAGE = Chinese
其它配置選項見：http://www.doxygen.nl/manual/config.html
3. 給代碼添加注釋
並不是所有的注釋都會被收入文檔，Doxygen 支持的常用的注釋風格有：
- 在全局作用域，類前 或 函數前 注釋
/** 注釋的內容 */
/*! 注釋的內容 */
- 文件成員，類成員，結構體成員，共同體成員，枚舉成員 或 函數參數 后注釋
int a; /**< 注釋的內容 */
int a; /*!< 注釋的內容 */
其它注釋風格見：http://doxygen.nl/manual/docblocks.html
Doxygen 常用的注釋標記（標記以 / 或 @ 開頭表示）：
- 添加簡單描述
@brief 簡要描述
- 添加詳細描述
@details 詳細描述
- 添加類信息
@class 類名 類所在的文件 類所在的文件（可包括路徑）
- 添加結構體信息
@struct 結構體名 結構體所在的文件 結構體所在的文件（可包括路徑）
- 添加參數說明
@param [in] 輸入參數名 說明
@param [out] 輸出參數名 說明
- 添加返回說明
@return 返回說明
- 添加返回特定值說明
@retval 特定值 特定返回值說明
- 添加異常說明
@exception 異常類型 異常說明
- 添加代碼
@code
...代碼...
@encode
- 添加計划做的事兒
@todo 計划做的事
- 添加參考
@see 參考其它
- 添加過時說明
@deprecated 過時說明
- 添加 bug 說明
@bug "bug 說明"
- 添加例子
@example 例子文件名
- 添加警告信息
@warning 警告信息
- 添加開始使用的版本
@since 版本
- 添加注意事項
@note 注意事項
其它標記選項見：http://www.doxygen.nl/manual/commands.html
4. 生成文檔
$ doxygen <config-file>