前言

下面主要講解linux下Doxygen命令行實(shí)現(xiàn)html文檔生成的操作，當(dāng)然也有界面版本操作方式，linux下安裝doxygen-gui即可通過doxywizard開啟界面操作，windows下也可以通過doxywizard.exe界面進(jìn)行配置操作，具體的界面操作請(qǐng)參考其他網(wǎng)上文章，不過有一句話需要說明：會(huì)命令行操作的，應(yīng)該都會(huì)界面操作，而會(huì)界面操作的就不一定會(huì)命令行操作了。

windows下的操作方式可以參考 使用doxygen生成chm范例

doxygen是什么

按照約定的格式注釋源代碼，用工具處理注釋過的源代碼產(chǎn)生文檔。通過這種方式產(chǎn)生文檔至少有以下好處：

便于代碼和文檔保持同步

可以對(duì)文檔做版本管理

Doxygen就是這樣的工具，Doxygen是一個(gè)程序的文件產(chǎn)生工具，可將程序中的特定批注轉(zhuǎn)換成為說明文件。很多編程語言都有類似的文檔工具，例如：Java有javadoc，Ruby有rdoc。對(duì)于C/C++程序，我們可以用Doxygen生成文檔。Doxygen有如下特點(diǎn)：

支持的編程語言：完全支持 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等類似工具；

支持平臺(tái)：Unix(包括Linux)、MacOs、Windows等；

主頁(yè)：http://www.doxygen.org/

郵件列表：

doxygen-user@lists.sourceforge.net

doxygen-develop@lists.sourceforge.net

作者：Dimitri van Heesch (dimitri@stack.nl) ；

Doxygen基本操作流程

按照Doxygen的約定，將代碼“文檔化”。這部分請(qǐng)參考 代碼‘文檔化’；

編寫一個(gè)配置文件(Doxyfile)，用于配合Doxygen生成最終的文檔。這部分請(qǐng)參考 編寫一個(gè)Doxygen配置文件；

執(zhí)行doxygen Doxyfile生成文檔。

下面詳細(xì)介紹每一個(gè)步驟。

代碼‘文檔化’

這一部分需要了解基本的注釋規(guī)則和doxygen注釋標(biāo)記

doxygen注釋規(guī)則

并非所有程序代碼中的注釋都會(huì)被 Doxygen 處理(除非在配置文件里使能了EXTRACT_ALL等選項(xiàng))，必需依照正確的格式撰寫，Doxygen 可處理下面兩種類型的注解(注意：默認(rèn)采用的JavaDoc風(fēng)格，你也可以選擇采用Qt或者c/c++風(fēng)格),如下:

/**

* ...多行注釋...

*

*/

/** ...單行注釋... */

由于 Doxygen 認(rèn)為注釋是說明它下面的程序代碼。所以,如果注釋要與前面的程序碼在同一行內(nèi),則需用下面這種型式的注釋:

/**< ...代碼同行情況的注釋 */

注意,除**后多了一個(gè)

首先,我們先說明在 Doxygen 中對(duì)於類別或是函數(shù)注解的一個(gè)特定格式。

/**

*

* struct、class、functiond的簡(jiǎn)易說明...

*

* struct、class、functiond的詳細(xì)說明...

* ...

*/

上面這個(gè)例子要說的是,在 Doxygen 處理一個(gè)類定義或是函數(shù)定義之上的注釋時(shí):

會(huì)先判斷第一行為簡(jiǎn)易說明,這個(gè)簡(jiǎn)易說明將一直到遇見一個(gè)空白行的出現(xiàn)或是遇到第一個(gè) . 為止;

之后的注解將會(huì)被視為詳細(xì)說明。

另一種比較清楚的方式是指定@brief 的指令,這將會(huì)明確的告訴 Doxygen 哪個(gè)是簡(jiǎn)易說明。

doxygen在處理注釋文檔的時(shí)候，會(huì)進(jìn)行如下的過程：

執(zhí)行在文檔中的特殊命令。命令都以''或'@'開始,二者是一樣的，都是為了引出一個(gè)命令。例如'\brief','\details','@brief', '@details'等等。

如果一行以空白開始，后面跟著一個(gè)或者多個(gè)''，然后又跟著0個(gè)或者多個(gè)空白，那么所有的空白和''將會(huì)被移除。

所有的空行將會(huì)被當(dāng)作段分隔符號(hào)。

為相應(yīng)的被文檔化了的類的單詞創(chuàng)建相應(yīng)的鏈接(除非這個(gè)單詞前面放置一個(gè)'%'，這時(shí)候就沒有鏈接了并且'%'也會(huì)被移走了)。

如果在文本中發(fā)現(xiàn)了相應(yīng)的匹配，會(huì)建立成員的鏈接。(?)

文檔中的HTML標(biāo)記會(huì)被解釋、轉(zhuǎn)化為L(zhǎng)ATEX的東西以便成為L(zhǎng)ATEX的輸出。(?)

Doxygen常用的代碼注釋標(biāo)記

文件信息

@file 文件名(遵守文件命名規(guī)則) --> 文件聲明，即當(dāng)前文件名

@author 作者名 --> 作者

@version 版本號(hào) --> 版本號(hào)

@todo 說明文字 --> TODO 列表，在相關(guān)頁(yè)面有它專門一項(xiàng)

注:只能在實(shí)現(xiàn)文件(.c/.cpp)中使用，如果相同函數(shù)的實(shí)現(xiàn)文件與頭文件中均有，生成的文檔中會(huì)有重復(fù)項(xiàng)，可以理解為調(diào)用者不應(yīng)知道實(shí)現(xiàn)流程

@date 日期時(shí)間 --> 說明文件生成的日期時(shí)間

@section 章節(jié)標(biāo)題 --> @section LICENSE 版權(quán)許可 @section DESCRIPTION 描述

模塊信息

@defgroup 模塊名(英文) 顯示名(中文) @{ 類/函數(shù)/變量/宏/... @}--> 定義模塊

@ingroup 模塊名(英文) [顯示名(中文)]--> 作為指定名的模塊的子模塊,顯示名為可選項(xiàng),可與指定名的模塊的顯示名不同

@addtogroup 模塊名(英文) [顯示名(中文)] --> 作為指定名的模塊的成員,顯示名為可選項(xiàng),必需與指定名的模塊的顯示名相同

@name 顯示名(中文) @{ 變量/宏 @} --> 按用途分,以便理解全局變量/宏的用途

這部分推薦參考： doxygen使用總結(jié)

函數(shù)信息

@param 參數(shù)名 說明文字 --> 不建議使用這個(gè)

@param[in] 參數(shù)名 說明文字 --> 輸入?yún)?shù)

@param[out] 參數(shù)名 說明文字 --> 輸出參數(shù)

@param[in,out] 參數(shù)名 說明文字 --> 即輸入又輸出參數(shù)

@exception 用來說明異常類及拋出條件

@remark 表示評(píng)論，暴露給客戶程序員的文檔

@return 說明文字 --> 返回值說明

@retval 說明文字 --> 特定返回值說明

@note 說明文字 --> 注解,可以描述工作流程和注意事項(xiàng)

@par [段落標(biāo)題] --> 開創(chuàng)新段落,一般與示例代碼聯(lián)用

@code --> 示例代碼開始

@endcode --> 示例代碼結(jié)束

@see 類/函數(shù)/變量/文件/URL --> 參見,

類名::函數(shù)名 或 ::函數(shù)名 可以變成超鏈接點(diǎn)擊跳轉(zhuǎn)到對(duì)應(yīng)函數(shù)說明處

函數(shù)重載的情況下,要帶上參數(shù)列表以及返回值

@deprecated 說明文字 --> 過時(shí)列表,在相關(guān)頁(yè)面有它專門一項(xiàng)

注:只能在頭文件(*.h)中使用,如果相同函數(shù)的實(shí)現(xiàn)文件與頭文件中均有,

生成的文檔中會(huì)有重復(fù)項(xiàng),可以理解為維護(hù)者不關(guān)心這個(gè)接口是不是要過時(shí)

@pre 說明文字 --> 前置條件

@arg 參數(shù)/返回值 說明文字 --> 以列表形式說明參數(shù)取值意義

注:也可以用 - 或 -# 來代替,建議此種方法,簡(jiǎn)單明了

- 第一級(jí)

- 第二級(jí)

- 第三級(jí)

即相同開頭的-或 -#第二行比第一行縮進(jìn)一個(gè)英文空格就變了第二級(jí),依次類推

- 開頭的第一級(jí)為實(shí)心黑圓點(diǎn);第二級(jí)為空心黑圓點(diǎn);第三級(jí)以后為實(shí)心方塊;

-#開頭的第一級(jí)為數(shù)字(1./2./3./...),

第二級(jí)為小寫字母(a./b./c./...),

第三級(jí)為羅馬數(shù)字(i./ii./iii./...),

第四級(jí)為大寫字母(A./B./C./...)

提醒信息

@brief 說明文字 --> 摘要,即當(dāng)前文件/函數(shù)說明

@attention 說明文字 --> 注意

@bug 說明文字 --> 問題

@warning 說明文字 --> 警告

@ref 引用其他標(biāo)記，類似于html中的錨

@since {text} 通常用來說明從什么版本、時(shí)間寫此部分代碼

@relates 通常用做把非成員函數(shù)的注釋文檔包含在類的說明文檔中

@def 宏定義說明

@fn 函數(shù) 函數(shù)說明

@test 測(cè)試示例、信息

(@bug、@test以及@todo等會(huì)出現(xiàn)鏈接頁(yè)面)

下面為生成特殊字體的命令：

@a @e @em：其后的單個(gè)字(word)表現(xiàn)為斜體，以強(qiáng)調(diào)作用。如有多個(gè)word的話，使用xxx xxx代替

@b：其后的word為粗體，多個(gè)則使用xxx xxx

@c @p：字體表現(xiàn)為打印機(jī)字體，多個(gè)則使用xxx xxx

@enum 引用了某個(gè)枚舉，Doxygen會(huì)在該枚舉處產(chǎn)生一個(gè)鏈接 eg：@enum CTest::MyEnum

@var 引用了某個(gè)變量，Doxygen會(huì)在該枚舉處產(chǎn)生一個(gè)鏈接 eg：@var CTest::m_FileKey

@class 引用某個(gè)類，格式：@class [] [] eg:@class CTest "inc/class.h"

下面舉例說明可能遇到的幾種情況：

文件注釋

/**

* @file

* @author rongp

* @version 1.0.0

* @date 2016/02/22

*

* @section LICENSE

*

* Copyright(c) 2015-2020 XXX

* All rights reserved

*

* @brief iss服務(wù)器端sdk導(dǎo)出根文件

*

* @section DESCRIPTION

* 界面開發(fā)者只需要包含該頭文件即可, 具體的導(dǎo)出數(shù)據(jù)結(jié)構(gòu)、api分別分別在

* net_io_export.h和app_amp_export.h中

*

*/

函數(shù)注釋

/**

* @brief 創(chuàng)建與本地服務(wù)通訊的端點(diǎn)

* @param[in] proto_type 端點(diǎn)通訊采用的協(xié)議類型, 一般設(shè)置為PROTO_TYPE_TRANS即可

*

* @return 用于通訊的端點(diǎn)指針，作為后面接口的參數(shù)

* @retval non-NULL 成功

* @retval NULL 出錯(cuò)

*

* @warning 該接口只能在服務(wù)端sdk使用, 當(dāng)前只支持PROTO_TYPE_TRANS協(xié)議類型

*

* 示例

@code

gpointer e = net_io_create_local_endpoint(PROTO_TYPE_TRANS);

@endcode

*

* @since 1.0.0

*/

結(jié)構(gòu)體注釋

/**

* @brief 服務(wù)器信息描述結(jié)構(gòu)

*/

struct _ServerInfo {

/** 服務(wù)器系統(tǒng)版本, 包括硬件信息、操作系統(tǒng)信息等 */

gchar sys_ver[128];

/** 服務(wù)器軟件版本 */

gchar soft_ver[128];

};

枚舉注釋

/**

* @brief 消息返回碼

*/

enum MSG_RET_CODE {

/** 執(zhí)行成功 */

MSG_EXECUTE_OK = 0,

/** 超時(shí) */

MSG_TIMEOUT = -1,

/** 消息的大小有誤 */

MSG_SIZE_UNMATCH = -2,

/** 不允許執(zhí)行該消息 */

MSG_OPT_FORBID = -3,

/** 服務(wù)器端服務(wù)出錯(cuò) */

MSG_SYSTEM_ERR = -4,

/** 消息的參數(shù)有誤 */

MSG_ARG_INVALID = -5,

/** buf內(nèi)存不夠 */

MSG_NOMEM = -100,

};

編寫一個(gè)Doxygen配置文件

一般是通過先生成模板配置文件，然后基于模板配置文件修改即可。使用 "doxygen -g" 命令在當(dāng)前目錄下生成名為‘Doxyfile’的配置文件模板。也可以采用 "doxygen -g filename" 命令格式指定所生成的配置文件名為filename。如無特殊需要，采用默認(rèn)的配置文件名即可。如果對(duì) Doxygen 各配置選項(xiàng)的意義有一定了解，可以在生成配置文件的命令中添加 "-s" 選項(xiàng)，生成不含注釋的配置文件，如:doxygen -s -g 這種方式生成的配置文件非常精簡(jiǎn)，沒有任何注釋。

有了doxygen模板配置文件后，現(xiàn)在要做的就是對(duì)它進(jìn)行修改了，下面以c語言開發(fā)的項(xiàng)目生成html為例。主要有下面幾個(gè)選項(xiàng)需要修改：

# 項(xiàng)目名稱，將作為于所生成的程序文檔首頁(yè)標(biāo)題，需要使用雙引號(hào)括住

PROJECT_NAME = “xxx”

# 文檔版本號(hào)，可對(duì)應(yīng)于項(xiàng)目版本號(hào)，譬如 git、svn、cvs 所生成的項(xiàng)目版本號(hào)

PROJECT_NUMBER = “1.0.0”

# 程序文檔輸出目錄，產(chǎn)生的文件會(huì)放在這個(gè)路徑之下。如果沒有填這個(gè)路徑，將會(huì)以當(dāng)前所在路徑來作為輸出路徑。

OUTPUT_DIRECTORY = doc/

# 程序文檔語言環(huán)境，預(yù)設(shè)為 English。1.2.16 版后，可以用 Chinese 輸出簡(jiǎn)體中文，也可以使用

# Chinese-Traditional 來輸出中文繁體的格式。

OUTPUT_LANGUAGE = Chinese

# 如果是制作 C 程序文檔，該選項(xiàng)必須設(shè)為YES，否則默認(rèn)生成 C++ 文檔格式

OPTIMIZE_OUTPUT_FOR_C = YES

# 對(duì)于使用 typedef 定義的結(jié)構(gòu)體、枚舉、聯(lián)合等數(shù)據(jù)類型，只按照 typedef 定義的類型名進(jìn)行文檔化

TYPEDEF_HIDES_STRUCT = YES

# 把這個(gè)標(biāo)記設(shè)置為Yes，即使各個(gè)類或函數(shù)沒有文檔，也要提取信息

EXTRACT_ALL = YES

# 把這個(gè)標(biāo)記設(shè)置為Yes，文檔就會(huì)包含類的私有數(shù)據(jù)成員

EXTRACT_PRIVATE = YES

# 把這個(gè)標(biāo)記設(shè)置為Yes，文檔就會(huì)包含文件的靜態(tài)成員(函數(shù)和變量)

EXTRACT_STATIC = YES

# 在 C++ 程序文檔中,該值可以設(shè)置為 NO，而在 C 程序文檔中，由于 C 語言沒有所謂的域/名字空間

# 這樣的概念，所以此處設(shè)置為 YES

HIDE_SCOPE_NAMES = YES

# 讓 doxygen 靜悄悄地為你生成文檔，只有出現(xiàn)警告或錯(cuò)誤時(shí)，才在終端輸出提示信息

QUIET = YES

# 這個(gè)標(biāo)記創(chuàng)建一個(gè)以空格分隔的所有目錄的列表，

# 這個(gè)列表包含需要生成文檔的 C/C++ 源代碼文件和頭文件，可以不設(shè)定，即為當(dāng)前目錄!

INPUT = inc/

# 輸入文件的編碼格式，需要自己根據(jù)INPUT指定的文件選擇，否則會(huì)亂碼

INPUT_ENCODING = UTF-8

# 在默認(rèn)情況下,doxygen 會(huì)搜索具有典型 C/C++ 擴(kuò)展名的文件，

# 比如 .c、.cc、.cpp、.h 和 .hpp 。

# 可以使用如下形式的列表方式,指定INPUT下要處理的文件

# 注:文件類型后有空格然后是右斜杠然后回車,每一個(gè)文件類均獨(dú)自一行!

# FILE_PATTERNS = *.h \

*.c \

*.cpp

FILE_PATTERNS =

# 遞歸遍歷由 INPUT 所指定的目錄及其所有子目錄，尋找由 FILE_PATTERNS 指定的要被文檔化的文件

RECURSIVE = YES

# 如果您有特定文件或目錄，不希望經(jīng)過 Doxygen 處理，那你可在這指出，沒有就不指出

# 例如:EXCLUDE = /home/xxx/src_root /home/xxx/test

EXCLUDE =

# 類似于 FILE_PATTERNS 的用法，只是這個(gè)是供 EXCLUDE 所使用

EXCLUDE_PATTERNS =

# 若設(shè)定為 YES，就會(huì)產(chǎn)生 HTML 版本的說明文件。HTML 文件是 Doxygen 預(yù)設(shè)產(chǎn)生的格式之一

GENERATE_HTML = YES

# 若設(shè)定為 YES，Doxygen 會(huì)幫您產(chǎn)生一個(gè)樹狀結(jié)構(gòu)，在頁(yè)面左側(cè)，默認(rèn)為 NO

# 這個(gè)樹狀結(jié)構(gòu)是以 JavaScript 所寫成。所以需要新版的 Browser 才能正確顯示。

GENERATE_TREEVIEW = YES

其他可參考的：

文檔輸出格式

除了 HTML 之外，doxygen 還可以生成幾種輸出格式的文檔。可以讓 doxygen 生成以下格式的文檔：

UNIX 手冊(cè)頁(yè)：把 標(biāo)記設(shè)置為 Yes。在默認(rèn)情況下，會(huì)在 指定的目錄中創(chuàng)建 man 子文件夾，生成的文檔放在這個(gè)文件夾中。必須把這個(gè)文件夾添加到 MANPATH 環(huán)境變量中。

Rich Text Format(RTF)：把 標(biāo)記設(shè)置為 Yes。把 標(biāo)記設(shè)置為希望放置 .rtf 文件的目錄；在默認(rèn)情況下，文檔放在 OUTPUT_DIRECTORY 中的 rtf 子文件夾中。要想支持跨文檔瀏覽，應(yīng)該把 標(biāo)記設(shè)置為 Yes。如果設(shè)置這個(gè)標(biāo)記，生成的 .rtf 文件會(huì)包含跨文檔鏈接。

Latex：在默認(rèn)情況下，doxygen 生成 Latex 和 HTML 格式的文檔。在默認(rèn)的 Doxyfile 中， 標(biāo)記設(shè)置為 Yes。另外， 標(biāo)記設(shè)置為 Latex，這意味著會(huì)在 OUTPUT_DIRECTORY 中創(chuàng)建 latex 子文件夾并在其中生成 Latex 文件。

Microsoft? Compiled HTML Help(CHM)格式：把 標(biāo)記設(shè)置為 Yes。因?yàn)樵?UNIX 平臺(tái)上不支持這種格式，doxygen 只在保存 HTML 文件的文件夾中生成一個(gè) index.hhp 文件。您必須通過 HTML 幫助編譯器把這個(gè)文件轉(zhuǎn)換為 .chm 文件。

Extensible Markup Language(XML)格式：把 標(biāo)記設(shè)置為 Yes。(注意，doxygen 開發(fā)團(tuán)隊(duì)還在開發(fā) XML 輸出)。

按照上面的修改后，就可以執(zhí)行第三步，執(zhí)行命令doxygen Doxyfile生成文檔了。注意：這里的Doxyfile

為你實(shí)際的Doxygen配置文件名。

Doxygen與其他工具配合生成chm

Doxygen FAQ

6.1 中文問題：中文注釋在文檔中是亂碼

解決：在expert中的INPUT選項(xiàng)頁(yè)的INPUT_ENCODEING中填入“GB2312”，這樣基于GB的文本編輯器生成的代碼就可以正常使用了。

6.2 圖形問題：無法繪制類圖協(xié)作圖等圖形。

解決：首先確保安裝了graphviz for win，注意不是wingraphviz，后者是一個(gè)graphviz的com封裝，但是doxygen并不是基于它開發(fā)的，所以裝了也沒用。然后在expert的DOT_PATH中填入graphviz的安裝路徑。接著在wizard的diagram中選擇需要生成的圖形類別就可以了。

如果出現(xiàn)無法包含.map文件的錯(cuò)誤，可以將工作目錄設(shè)置成html，并將html中所有文件都清除再試。這個(gè)問題的原因還不太確定。

6.3 輸出chm的問題：如何輸出.chm文件

配置時(shí)注意expert中的HTML頁(yè)：選中“GENERATE_HTMLHELP”，然后在CHM_FILE中填上想要的chm文件名。

HHC_LOCATION中輸入hhc.exe文件的路徑。hhc.exe可以通過安裝HTML Help Workshop獲得。

或者使用HTML Help Workshop來編譯Doxygen生成的html文件夾中的.hhp文件，編譯完成后即可在該html文件夾中找到對(duì)應(yīng)的chm文件

6.4 Doxygen無法為DLL中定義的類 導(dǎo)出文檔

例如：

class __declspec(dllexport) CClassName:public CObject

{

}

目前發(fā)現(xiàn)Doxygen無法識(shí)別出DLL中定義的類。

http://ticktick.blog.51cto.com/823160/188674

未完，待續(xù)

2016年6月

總結(jié)

以上是生活随笔為你收集整理的doxygen 命令_doxygen使用的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。