Doxygen 入門教程

簡介

• 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>

參考資源

• http://doxygen.nl/