Doxygen使用教程個人總結(jié)

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

2、先是特定格式的批注撰寫，第二便是利用Doxygen的工具來產(chǎn)生文檔。目前Doxygen可處理的程序語言包含：· C/C+· Java· IDL (Corba, Microsoft及KDE-DCOP類型)   而可產(chǎn)生出來的文檔格式有：· HTML· XML· LaTeX· RTF· Unix Man Page而其中還可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透過一些工具產(chǎn)生出PS或是PDF文檔。二安裝Doxygen· 1.1 安裝 Doxygen 1.7.4(

3、Windows) · 1.2 安裝 graphviz 2.28.0(Windows)graphviz 是一個由AT&T實驗室啟動的開源工具包，用于繪制DOT語言腳本描述的圖形。Doxygen 使用 graphviz 自動生成類之間和文件之間的調(diào)用關(guān)系圖，如不需要此功能可不安裝該工具包。·Doxygen 使用這個工具可以生成 CHM 格式的文檔。三Doxygen的配置Doxygen 產(chǎn)生文檔可以分為三個步驟。一是在程序代碼中加上符合Doxygen所定義批注格式。二是使用Doxywizard進(jìn)行配置。三是使用Doxygen來產(chǎn)生批注文檔。Doxygen 1.7.4 主界

4、面如下圖 1 所示。 說明：1，Doxygen 工作目錄，就是用來存放配置文件的目錄。 2，遞歸搜索源文件目錄需要選上。選擇 wizard 標(biāo)簽下的 Output Topics相關(guān)配置說明如下圖 2 所示。 選擇 wizard 標(biāo)簽下的 Diagrams Topics相關(guān)配置說明如下圖 3 所示。說明：如果選擇這個選項之前需要先安裝了 Graphviz 工具包。選擇 expert 標(biāo)簽下的 Project Topics相關(guān)配置說明如下圖 4 所示。說明：編碼格式，UTF-8 是首選。如果需要顯示中文則選擇GB2313.TAB

5、_SIZE 主要是幫助文件中代碼的縮進(jìn)尺寸，譬如code和endcode段中代碼的排版，建議設(shè)置成4。OPTIMIZE_OUTPUT_FOR_C 這個選項選擇后，生成文檔的一些描述性名稱會發(fā)生變化，主要是符合C習(xí)慣。如果是純C代碼，建議選擇。SUBGROUPING這個選項選擇后，輸出將會按類型分組。選擇 expert 標(biāo)簽下的 BuildBuild頁面，這個頁面是生成幫助信息中比較關(guān)鍵的配置頁面：EXTRACT_ALL 表示：輸出所有的函數(shù)，但是private和static函數(shù)不屬于其管制。EXTRACT_PRIVATE 表示：輸出private函數(shù)。EXTRACT_STA

6、TIC 表示：輸出static函數(shù)。同時還有幾個EXTRACT，相應(yīng)查看文檔即可。HIDE_UNDOC_MEMBERS 表示：那些沒有使用doxygen格式描述的文檔（函數(shù)或類等）就不顯示了。當(dāng)然，如果EXTRACT_ALL被啟用，那么這個標(biāo)志其實是被忽略的。INTERNAL_DOCS 主要指：是否輸出注解中的internal部分。如果沒有被啟動，那么注解中所有的internal部分都將在目標(biāo)幫助中不可見。CASE_SENSE_NAMES 表示：是否關(guān)注大小寫名稱，注意，如果開啟了，那么所有的名稱都將被小寫。對于C/C+這種字母相關(guān)的語言來說，建議永遠(yuǎn)不要開啟。HIDE_SCOPE_NAMES

7、 表示：域隱藏，建議永遠(yuǎn)不要開啟。SHOW_INCLUDE_FILES 表示：是否顯示包含文件，如果開啟，幫助中會專門生成一個頁面，里面包含所有包含文件的列表。INLINE_INFO ：如果開啟，那么在幫助文檔中，inline函數(shù)前面會有一個inline修飾詞來標(biāo)明。SORT_MEMBER_DOCS ：如果開啟，那么在幫助文檔列表顯示的時候，函數(shù)名稱會排序，否則按照解釋的順序顯示。GENERATE_TODOLIST ：是否生成TODOLIST頁面，如果開啟，那么包含在todo注解中的內(nèi)容將會單獨生成并顯示在一個頁面中，其他的GENERATE選項同。SHOW_USED_FILES ：是否在函數(shù)或

8、類等的幫助中，最下面顯示函數(shù)或類的來源文件。SHOW_FILES ：是否顯示文件列表頁面，如果開啟，那么幫助中會存在一個一個文件列表索引頁面。選擇 expert 標(biāo)簽下的 Input Topics相關(guān)配置說明如下圖 5 所示。 說明：輸入的源文件的編碼，要與源文件的編碼格式相同。如果源文件不是UTF-8編碼最好轉(zhuǎn)一下。選擇 expert 標(biāo)簽下的 HTML Topics相關(guān)配置說明如下圖 6 所示。 說明：1，CHM_FILE文件名需要加上后綴（xx.chm）。2，如果在 Wizard 的 Output Topic

9、s 中選擇了 prepare for compressed HTML (.chm)選項，此處就會要求選擇 hhc.exe 程序的位置。在 windows help workshop 安裝目錄下可以找到 hhc.exe。3，為了解決DoxyGen生成的CHM文件的左邊樹目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312即可。4，GENERATE_CHI 表示索引文件是否單獨輸出，建議關(guān)閉。否則每次生成兩個文件，比較麻煩。5，TOC_EXPAND 表示是否在索引中列舉成員名稱以及分組（譬如函數(shù)，枚舉）名稱。選擇 Run 標(biāo)簽相關(guān)配置說明如下圖 7 所示

10、。  點擊 Run doxygen 按鈕， Doxygen 就會從源代碼中抓取符合規(guī)范的注釋生成你定制的格式的文檔。四撰寫正確格式的批注并非所有程序代碼中的批注都會被Doxygen 所處理。您必需依照正確的格式撰寫。原則上，Doxygen 僅處理與程序結(jié)構(gòu)相關(guān)的批注，如Function，Class ，檔案的批注等。對于Function內(nèi)部的批注則不做處理。Doxygen可處理下面幾種類型的批注。JavaDoc類型：/* * . 批注 . */Qt類型：/*! * . 批注 . */     單行

11、型式的批注：/ . 批注 .或    /! . 批注 .      要使用哪種型態(tài)完全看自己的喜好。以筆者自己來說，大范圍的注解我會使用JavaDoc 型的。單行的批注則使用"/" 的類型。此外，由于Doxygen 對于批注是視為在解釋后面的程序代碼。也就是說，任何一個批注都是在說明其后的程序代碼。如果要批注前面的程式碼則需用下面格式的批注符號。/*!< . 批注 . */*< . 批注 . */!< . 批注 ./< . 批注 .    上面這個方式

12、并不適用于任何地方，只能用在class 的member或是function的參數(shù)上。舉例來說，若我們有下面這樣的class。    class MyClass         public:            int member1 ;            int memb

13、er2:            void member_function();    ;    加上批注后，就變成這樣：    /*     * 我的自訂類別說明 .     */    class MyClass       &

14、#160; public:            int member1 ; /< 第一個member說明 .            int member2:  /< 第二個member說明 .            int member_func

15、tion(int a, int b);    ;        /*     * 自訂類別的member_funtion說明 .     *     * param a 參數(shù)a的說明     * param b 參數(shù)b的說明     *     * return 傳回a

16、+b。     */     int MyClass:member_function( int a, int b )             return a+b ;        當(dāng)您使用Doxygen 產(chǎn)生說明文檔時，Doxygen 會幫您parsing 您的程式碼。并且依據(jù)程序結(jié)構(gòu)建立對應(yīng)的文件。然后再將您的批注，依據(jù)其位置套入于正確的地方。您可能已經(jīng)注意到，除

17、了一般文字說明外，還有一些其它特別的指令，像是param及return 等。這正是Doxygen 另外一個重要的部分，因為一個類別或是函式其實都有固定幾個要說明的部分。為了讓Doxygen 能夠判斷，所有我們就必需使用這些指令，來告訴Doxygen 后面的批注是在說明什么東西。Doxygen 在處理時，就會幫您把這些部分做特別的處理或是排版。甚至是制作參考連結(jié)。首先，我們先說明在Doxygen 中對于類別或是函數(shù)批注的一個特定格式。    /*     * class或function的簡易說明.  &#

18、160;  *     * class或function的詳細(xì)說明.     * .     */     上面這個例子要說的是，在Doxygen 處理一個class 或是function注解時，會先判斷第一行為簡易說明。這個簡易說明將一直到空一行的出現(xiàn)?；蚴怯龅降谝粋€"." 為止。之后的批注將會被視為詳細(xì)說明。兩者的差異在于Doxygen 在某些地方只會顯示簡易說明，而不顯示詳細(xì)說明。如：class 或f

19、unction的列表。另一種比較清楚的方式是指定brief的指令。這將會明確的告訴Doxygen，何者是簡易說明。例如：    /*     * brief class或function的簡易說明.     *     * class或function的詳細(xì)說明.     * .     */除了這個class 及function外，Doxygen 也可針對檔案做說明

20、，條件是該批注需置于檔案的前面。主要也是利用一些指令，通常這部分注解都會放在檔案的開始地方。如：        brief 檔案簡易說明            詳細(xì)說明.                author 作者信息    */如您所見，檔案批注約略格

21、式如上，請別被"" 所搞混。其實，"" 與"" 都是一樣的，都是告訴Doxygen 后面是一個指令。兩種在Doxygen 都可使用。筆者自己比較偏好使用""。接著我們來針對一些常用的指令做說明：file檔案的批注說明。author作者的信息brief用于class 或function的批注中，后面為class 或function的簡易說明。param格式為param arg_name 參數(shù)說明主要用于函式說明中，后面接參數(shù)的名字，然后再接關(guān)于該參數(shù)的說明。return后面接函數(shù)傳回值的說明。用于function的批

22、注中。說明該函數(shù)的傳回值。retval格式為retval value 傳回值說明主要用于函式說明中，說明特定傳回值的意義。所以后面要先接一個傳回值。然后在放該傳回值的說明。       Doxygen 所支持的指令很多，有些甚至是關(guān)于輸出排版的控制。您可從Doxygen的使用說明中找到詳盡的說明。下面我們準(zhǔn)備一組example.h 及example.cpp 來說明Doxygen 批注的使用方式：example.h:    /*     * file 本范例的incl

23、ude檔案。     *     * 這個檔案只定義example這個class。     *     * author garyleelocalhost     */                #define EXAMPLE_OK  0

24、0;  /< 定義EXAMPLE_OK的宏為0。        /*     * brief Example class的簡易說明     *     * 本范例說明Example class。     * 這是一個極為簡單的范例。     *      */  

25、  class Example         private:            int var1 ; /< 這是一個private的變數(shù)        public:            int var2 ; /&

26、lt; 這是一個public的變數(shù)成員。            int var3 ; /< 這是另一個public的變數(shù)成員。            void ExFunc1(void);             int ExFunc2(int a, char b

27、);            char *ExFunc3(char *c) ;    ;        example.cpp:    /*     * file 本范例的程序代碼檔案。     *     * 這個檔案用來定義example這個cla

28、ss的     * member function。     *     * author garyleelocalhost     */        /*     * brief ExFunc1的簡易說明     *     * ExFunc1沒有任何參數(shù)及傳回值。     */    void Example:ExFunc1(void)            / empty funcion.        /*&#