當(dāng)前位置：首頁(yè) > 编程资源 > 编程问答 >内容正文

编程问答

Doxygen简介

發(fā)布時(shí)間：2023/12/13 编程问答 42 豆豆

生活随笔收集整理的這篇文章主要介紹了 Doxygen简介小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

（轉(zhuǎn)自：http://www.cnblogs.com/liuliunumberone/archive/2012/04/10/2441391.html）

一．什么是Doxygen?

Doxygen?是一個(gè)程序的文件產(chǎn)生工具，可將程序中的特定批注轉(zhuǎn)換成為說(shuō)明文件。通常我們?cè)趯?xiě)程序時(shí)，或多或少都會(huì)寫(xiě)上批注，但是對(duì)于其它人而言，要直接探索程序里的批注，與打撈鐵達(dá)尼號(hào)同樣的辛苦。大部分有用的批注都是屬于針對(duì)函式，類(lèi)別等等的說(shuō)明。所以，如果能依據(jù)程序本身的結(jié)構(gòu)，將批注經(jīng)過(guò)處理重新整理成為一個(gè)純粹的參考手冊(cè)，對(duì)于后面利用您的程序代碼的人而言將會(huì)減少許多的負(fù)擔(dān)。不過(guò)，反過(guò)來(lái)說(shuō)，整理文件的工作對(duì)于您來(lái)說(shuō)，就是沉重的負(fù)擔(dān)。
Doxygen 就是在您寫(xiě)批注時(shí)，稍微按照一些它所制訂的規(guī)則。接著，他就可以幫您產(chǎn)生出漂亮的文檔了。

因此，Doxygen 的使用可分為兩大部分。首先是特定格式的批注撰寫(xiě)，第二便是利用Doxygen的工具來(lái)產(chǎn)生文檔。

目前Doxygen可處理的程序語(yǔ)言包含：

C/C++
Java
IDL (Corba, Microsoft及KDE-DCOP類(lèi)型)??

而可產(chǎn)生出來(lái)的文檔格式有：

HTML
XML
LaTeX
RTF
Unix Man Page

而其中還可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透過(guò)一些工具產(chǎn)生出PS或是PDF文檔。

二．安裝Doxygen

1.1?安裝 Doxygen 1.7.4(Windows)　　?　　http://sourceforge.net/projects/doxygen/?
1.2?安裝 graphviz 2.28.0(Windows) ? ??　　http://www.graphviz.org/Download

graphviz?是一個(gè)由AT&T實(shí)驗(yàn)室啟動(dòng)的開(kāi)源工具包，用于繪制DOT語(yǔ)言腳本描述的圖形。Doxygen?使用 graphviz 自動(dòng)生成類(lèi)之間和文件之間的調(diào)用關(guān)系圖，如不需要此功能可不安裝該工具包。

1.3?安裝 Windows Help Workshop 1.32

Doxygen?使用這個(gè)工具可以生成 CHM 格式的文檔。

三．Doxygen的配置

Doxygen?產(chǎn)生文檔可以分為三個(gè)步驟。一是在程序代碼中加上符合Doxygen所定義批注格式。二是使用Doxywizard進(jìn)行配置。三是使用Doxygen來(lái)產(chǎn)生批注文檔。
Doxygen 1.7.4?主界面如下圖?1?所示。

?說(shuō)明：1，Doxygen?工作目錄，就是用來(lái)存放配置文件的目錄。

?????? 2，遞歸搜索源文件目錄需要選上。

選擇?wizard?標(biāo)簽下的?Output Topics

相關(guān)配置說(shuō)明如下圖?2?所示。

?選擇?wizard?標(biāo)簽下的?Diagrams Topics

相關(guān)配置說(shuō)明如下圖?3?所示。

說(shuō)明：如果選擇這個(gè)選項(xiàng)之前需要先安裝了?Graphviz?工具包。

選擇?expert?標(biāo)簽下的?Project Topics

相關(guān)配置說(shuō)明如下圖?4?所示。

說(shuō)明：編碼格式，UTF-8?是首選。如果需要顯示中文則選擇GB2313.

TAB_SIZE?主要是幫助文件中代碼的縮進(jìn)尺寸，譬如@code和@endcode段中代碼的排版，建議設(shè)置成4。

OPTIMIZE_OUTPUT_FOR_C?這個(gè)選項(xiàng)選擇后，生成文檔的一些描述性名稱(chēng)會(huì)發(fā)生變化，主要是符合C習(xí)慣。如果

是純C代碼，建議選擇。

SUBGROUPING這個(gè)選項(xiàng)選擇后，輸出將會(huì)按類(lèi)型分組。

選擇?expert?標(biāo)簽下的?Build

Build頁(yè)面，這個(gè)頁(yè)面是生成幫助信息中比較關(guān)鍵的配置頁(yè)面：

EXTRACT_ALL?表示：輸出所有的函數(shù)，但是private和static函數(shù)不屬于其管制。

EXTRACT_PRIVATE?表示：輸出private函數(shù)。

EXTRACT_STATIC?表示：輸出static函數(shù)。同時(shí)還有幾個(gè)EXTRACT，相應(yīng)查看文檔即可。

HIDE_UNDOC_MEMBERS?表示：那些沒(méi)有使用doxygen格式描述的文檔（函數(shù)或類(lèi)等）就不顯示了。當(dāng)然，如果EXTRACT_ALL被啟用，那么這個(gè)標(biāo)志其實(shí)是被忽略的。

INTERNAL_DOCS?主要指：是否輸出注解中的@internal部分。如果沒(méi)有被啟動(dòng)，那么注解中所有的@internal部分都

將在目標(biāo)幫助中不可見(jiàn)。

CASE_SENSE_NAMES?表示：是否關(guān)注大小寫(xiě)名稱(chēng)，注意，如果開(kāi)啟了，那么所有的名稱(chēng)都將被小寫(xiě)。對(duì)于C/C++這種

字母相關(guān)的語(yǔ)言來(lái)說(shuō)，建議永遠(yuǎn)不要開(kāi)啟。

HIDE_SCOPE_NAMES?表示：域隱藏，建議永遠(yuǎn)不要開(kāi)啟。

SHOW_INCLUDE_FILES?表示：是否顯示包含文件，如果開(kāi)啟，幫助中會(huì)專(zhuān)門(mén)生成一個(gè)頁(yè)面，里面包含所有包含文件的列

表。

INLINE_INFO?：如果開(kāi)啟，那么在幫助文檔中，inline函數(shù)前面會(huì)有一個(gè)inline修飾詞來(lái)標(biāo)明。

SORT_MEMBER_DOCS?：如果開(kāi)啟，那么在幫助文檔列表顯示的時(shí)候，函數(shù)名稱(chēng)會(huì)排序，否則按照解釋的順序顯

示。

GENERATE_TODOLIST?：是否生成TODOLIST頁(yè)面，如果開(kāi)啟，那么包含在@todo注解中的內(nèi)容將會(huì)單獨(dú)生成并顯

示在一個(gè)頁(yè)面中，其他的GENERATE選項(xiàng)同。

SHOW_USED_FILES?：是否在函數(shù)或類(lèi)等的幫助中，最下面顯示函數(shù)或類(lèi)的來(lái)源文件。

SHOW_FILES?：是否顯示文件列表頁(yè)面，如果開(kāi)啟，那么幫助中會(huì)存在一個(gè)一個(gè)文件列表索引頁(yè)面。

選擇?expert?標(biāo)簽下的?Input Topics

相關(guān)配置說(shuō)明如下圖?5?所示。

說(shuō)明：輸入的源文件的編碼，要與源文件的編碼格式相同。如果源文件不是UTF-8編碼最好轉(zhuǎn)一下。

選擇?expert?標(biāo)簽下的?HTML Topics

相關(guān)配置說(shuō)明如下圖?6?所示。

說(shuō)明：1，CHM_FILE文件名需要加上后綴（xx.chm）。

2，如果在?Wizard?的?Output Topics?中選擇了?prepare for compressed HTML (.chm)選項(xiàng)，此處就會(huì)要求選擇?hhc.exe?程序的位置。在?windows help workshop?安裝目錄下可以找到?hhc.exe。

3，為了解決DoxyGen生成的CHM文件的左邊樹(shù)目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312即可。

4，GENERATE_CHI?表示索引文件是否單獨(dú)輸出，建議關(guān)閉。否則每次生成兩個(gè)文件，比較麻煩。

5，TOC_EXPAND?表示是否在索引中列舉成員名稱(chēng)以及分組（譬如函數(shù)，枚舉）名稱(chēng)。

選擇?Run?標(biāo)簽

相關(guān)配置說(shuō)明如下圖?7?所示。

??點(diǎn)擊?Run doxygen?按鈕，?Doxygen?就會(huì)從源代碼中抓取符合規(guī)范的注釋生成你定制的格式的文檔。

四．撰寫(xiě)正確格式的批注

并非所有程序代碼中的批注都會(huì)被Doxygen 所處理。您必需依照正確的
格式撰寫(xiě)。原則上，Doxygen 僅處理與程序結(jié)構(gòu)相關(guān)的批注，如
Function，Class ，檔案的批注等。對(duì)于Function內(nèi)部的批注則不做
處理。Doxygen可處理下面幾種類(lèi)型的批注。

JavaDoc類(lèi)型：

/**
?* ...?批注 ...
?*/

Qt類(lèi)型：

/*!
?* ...?批注 ...
?*/

?????
單行型式的批注：

/// ...?批注 ...

或???

//! ...?批注 ...

????
??
要使用哪種型態(tài)完全看自己的喜好。以筆者自己來(lái)說(shuō)，大范圍的注
解我會(huì)使用JavaDoc 型的。單行的批注則使用"///" 的類(lèi)型。

此外，由于Doxygen 對(duì)于批注是視為在解釋后面的程序代碼。也就是
說(shuō)，任何一個(gè)批注都是在說(shuō)明其后的程序代碼。如果要批注前面的程
式碼則需用下面格式的批注符號(hào)。

/*!< ...?批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...

????
上面這個(gè)方式并不適用于任何地方，只能用在class 的member或是
function的參數(shù)上。

舉例來(lái)說(shuō)，若我們有下面這樣的class。

??? class MyClass {
??????? public:
??????????? int member1 ;
??????????? int member2:
??????????? void member_function();
??? };
????
加上批注后，就變成這樣：

??? /**
???? * 我的自訂類(lèi)別說(shuō)明 ...
???? */
??? class MyClass {
??????? public:
??????????? int member1 ; ///< 第一個(gè)member說(shuō)明 ...
??????????? int member2:? ///< 第二個(gè)member說(shuō)明 ...
??????????? int member_function(int a, int b);
??? };
????
??? /**
???? * 自訂類(lèi)別的member_funtion說(shuō)明 ...
???? *
???? * @param a 參數(shù)a的說(shuō)明
???? * @param b 參數(shù)b的說(shuō)明
???? *
???? * @return 傳回a+b。
???? */?
??? int MyClass::member_function( int a, int b )?
??? {
??????? return a+b ;
??? }
????
當(dāng)您使用Doxygen 產(chǎn)生說(shuō)明文檔時(shí)，Doxygen 會(huì)幫您parsing 您的程
式碼。并且依據(jù)程序結(jié)構(gòu)建立對(duì)應(yīng)的文件。然后再將您的批注，依據(jù)
其位置套入于正確的地方。您可能已經(jīng)注意到，除了一般文字說(shuō)明外
，還有一些其它特別的指令，像是@param及@return 等。這正是
Doxygen 另外一個(gè)重要的部分，因?yàn)橐粋€(gè)類(lèi)別或是函式其實(shí)都有固定
幾個(gè)要說(shuō)明的部分。為了讓Doxygen 能夠判斷，所有我們就必需使用
這些指令，來(lái)告訴Doxygen 后面的批注是在說(shuō)明什么東西。Doxygen?
在處理時(shí)，就會(huì)幫您把這些部分做特別的處理或是排版。甚至是制作
參考連結(jié)。

首先，我們先說(shuō)明在Doxygen 中對(duì)于類(lèi)別或是函數(shù)批注的一個(gè)特定格
式。

??? /**
???? * class或function的簡(jiǎn)易說(shuō)明...
???? *
???? * class或function的詳細(xì)說(shuō)明...
???? * ...
???? */
?????
上面這個(gè)例子要說(shuō)的是，在Doxygen 處理一個(gè)class 或是function注
解時(shí)，會(huì)先判斷第一行為簡(jiǎn)易說(shuō)明。這個(gè)簡(jiǎn)易說(shuō)明將一直到空一行的
出現(xiàn)。或是遇到第一個(gè)"." 為止。之后的批注將會(huì)被視為詳細(xì)說(shuō)明。
兩者的差異在于Doxygen 在某些地方只會(huì)顯示簡(jiǎn)易說(shuō)明，而不顯示詳
細(xì)說(shuō)明。如：class 或function的列表。

另一種比較清楚的方式是指定@brief的指令。這將會(huì)明確的告訴
Doxygen，何者是簡(jiǎn)易說(shuō)明。例如：

??? /**
???? * @brief class或function的簡(jiǎn)易說(shuō)明...
???? *
???? * class或function的詳細(xì)說(shuō)明...
???? * ...
???? */

除了這個(gè)class 及function外，Doxygen 也可針對(duì)檔案做說(shuō)明，條件
是該批注需置于檔案的前面。主要也是利用一些指令，通常這部分注
解都會(huì)放在檔案的開(kāi)始地方。如：

??? /*! \file myfile.h
??????? \brief 檔案簡(jiǎn)易說(shuō)明
????
??????? 詳細(xì)說(shuō)明.
????????
??????? \author 作者信息
??? */

如您所見(jiàn)，檔案批注約略格式如上，請(qǐng)別被"\" 所搞混。其實(shí)，"\"?
與"@" 都是一樣的，都是告訴Doxygen 后面是一個(gè)指令。兩種在
Doxygen 都可使用。筆者自己比較偏好使用"@"。

接著我們來(lái)針對(duì)一些常用的指令做說(shuō)明：

@file	檔案的批注說(shuō)明。
@author	作者的信息
@brief	用于class 或function的批注中，后面為class 或function的簡(jiǎn)易說(shuō)明。
@param	格式為 @param arg_name?參數(shù)說(shuō)明主要用于函式說(shuō)明中，后面接參數(shù)的名字，然后再接關(guān)于該參數(shù)的說(shuō)明。
@return	后面接函數(shù)傳回值的說(shuō)明。用于function的批注中。說(shuō)明該函數(shù)的傳回值。
@retval	格式為 @retval value?傳回值說(shuō)明主要用于函式說(shuō)明中，說(shuō)明特定傳回值的意義。所以后面要先接一個(gè)傳回值。然后在放該傳回值的說(shuō)明。

???????
Doxygen?所支持的指令很多，有些甚至是關(guān)于輸出排版的控制。您可從Doxygen的使用說(shuō)明中找到詳盡的說(shuō)明。

下面我們準(zhǔn)備一組example.h 及example.cpp 來(lái)說(shuō)明Doxygen 批注的使用方式：

example.h:

??? /**
???? * @file 本范例的include檔案。
???? *
???? * 這個(gè)檔案只定義example這個(gè)class。
???? *
???? * @author garylee@localhost
???? */
????????????
??? #define EXAMPLE_OK? 0?? ///< 定義EXAMPLE_OK的宏為0。
????
??? /**
???? * @brief Example class的簡(jiǎn)易說(shuō)明
???? *
???? * 本范例說(shuō)明Example class。
???? * 這是一個(gè)極為簡(jiǎn)單的范例。
???? *?
???? */
??? class Example {
??????? private:
??????????? int var1 ; ///< 這是一個(gè)private的變數(shù)
??????? public:
??????????? int var2 ; ///< 這是一個(gè)public的變數(shù)成員。
??????????? int var3 ; ///< 這是另一個(gè)public的變數(shù)成員。
??????????? void ExFunc1(void);?
??????????? int ExFunc2(int a, char b);
??????????? char *ExFunc3(char *c) ;
??? };
????
????
example.cpp:

??? /**
???? * @file 本范例的程序代碼檔案。
???? *
???? * 這個(gè)檔案用來(lái)定義example這個(gè)class的
???? * member function。
???? *
???? * @author garylee@localhost
???? */
????
??? /**
???? * @brief ExFunc1的簡(jiǎn)易說(shuō)明
???? *
???? * ExFunc1沒(méi)有任何參數(shù)及傳回值。
???? */
??? void Example::ExFunc1(void)
??? {
??????? // empty funcion.
??? }

??? /**
???? * @brief ExFunc2的簡(jiǎn)易說(shuō)明
???? *
???? * ExFunc3()傳回兩個(gè)參數(shù)相加的值。
???? *
???? * @param a 用來(lái)相加的參數(shù)。
???? * @param b 用來(lái)相加的參數(shù)。
???? * @return 傳回兩個(gè)參數(shù)相加的結(jié)果。
???? */
??? int ExFunc2(int a, char b)
??? {
??????? return (a+b);
??? }
????
??? /**
???? * @brief ExFunc3的簡(jiǎn)易說(shuō)明
???? *
???? * ExFunc3()只傳回參數(shù)輸入的指標(biāo)。
???? *
???? * @param c 傳進(jìn)的字符指針。
???? * @retval NULL 空字符串。
???? * @retval !NULL 非空字符串。
???? */
??? char * ExFunc2(char * c)
??? {
??????? return c;
??? }????

轉(zhuǎn)載于:https://www.cnblogs.com/FindSelf/p/3713756.html

總結(jié)

以上是生活随笔為你收集整理的Doxygen简介的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

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