Doxygen是什么？
Doxygen是一種開源跨平臺(tái)的，以類似JavaDoc風(fēng)格描述的文檔系統(tǒng)，完全支持C、C++、Java、Objective-C和IDL語言，部分支持PHP、C#。注釋的語法與Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線的LATEX、RTF參考手冊(cè)。對(duì)于未歸檔的源文件，也可以通過配置Doxygen來提取代碼結(jié)構(gòu)。或者借助自動(dòng)生成的包含依賴圖（include dependency graphs）、繼承圖（inheritance diagram）以及協(xié)作圖（collaboration diagram）來可視化文檔之間的關(guān)系。Doxygen生成的幫助文檔的格式可以是CHM、RTF、PostScript、PDF、HTML和Unix man page等。
Doxygen在Linux上開發(fā)，但也可以在其它的Unix平臺(tái)下運(yùn)行。而且，Windows 9x/NT平臺(tái)下也有對(duì)應(yīng)的可執(zhí)行版本。
安裝Doxygen
首先，去Doxygen網(wǎng)站上找到最新版本的Doxygen。有二進(jìn)制或源碼兩種版本，如果不想重頭編譯，下載二進(jìn)制版本安裝即可。在Linux下，源碼編譯需要perl和Gnu工具flex、bison、make的支持。在Windows下，二進(jìn)制版本勿需安裝，而源碼編譯所需支持工具較多。我們僅講述Linux下的Doxygen的源碼編譯以及二進(jìn)制版本安裝過程。
編譯源碼
gunzip doxygen-$VERSION.src.tar.gztar xf doxygen-$VERSION.src.tarsh ./configure，或者configure --platform platform-type（略去直接使用configure需要平臺(tái)檢測(cè)的過程，平臺(tái)類型在PLATFORMS文件中列出），configure --with-doxywizard（GUI前端選項(xiàng)）make，或者make docs（創(chuàng)建HTML格式的手冊(cè)），make pdf（創(chuàng)建PDF格式的手冊(cè)）
|
安裝二進(jìn)制版本
二進(jìn)制文件安裝目錄是<prefix>/bin，其中<prefix>缺省為/usr，可以通過configure的參數(shù)--prefix修改其值。使用make install_docs可以把文檔和例子安裝在目錄<docdir>/doxygen，其中<docdir>缺省為<prefix>/share/doc/packages，可以通過configure的參數(shù)--docdir修改其值。doxygen是bin目錄下的一個(gè)命令行程序，它是Doxygen的核心工具，完成文檔的轉(zhuǎn)換和生成工作。
Doxygen的處理流程
圖1是Doxygen網(wǎng)站上給出的Doxygen處理工具以及它們之間的信息流。
從圖中可以看出，Doxygen可執(zhí)行程序位于正中，所有的流程都圍繞著它進(jìn)行。左側(cè)圖標(biāo)表示Doxygen的輸入可以是源文件，或者是定制的頭文件、圖像、注解等。Doxygen圖標(biāo)上部是配置文件，由Doxywizard處理，下部是Tag文件，由Doxytag處理。后面是Doxygen輸出文件的類型，依次是XML、Latex、Man pages、RTF和HTML，可處理類型圖標(biāo)之后是進(jìn)行進(jìn)一步轉(zhuǎn)換所需的工具。
圖1 Doxygen網(wǎng)站上給出的Doxygen信息流圖
配置文件
每一個(gè)Doxygen工程都有一個(gè)后綴為.cfg的配置文件，用來保存所有的設(shè)置。配置文件的格式與autoexec.bat、config.sys等文件相似，是由名稱/值對(duì)組成的ASCII碼，會(huì)由doxygen命令來解析。為了簡(jiǎn)化創(chuàng)建和修改配置文件，Doxygen可以在命令行方式下加上參數(shù)-g自動(dòng)創(chuàng)建模板文件。
doxygen -g <config-file>
忽略<config-file>將會(huì)生成一個(gè)名為Doxyfile的缺省文件，如果<config-file>已經(jīng)存在，會(huì)被Doxygen改名為<config-file>.bak。
實(shí)際上，我們根本就不需要用一般的編輯器來編輯配置文件，Doxygen提供了一個(gè)輔助工具Doxywizard。Doxywizard是Doxygen的GUI前臺(tái)，用戶可以能過它來讀寫配置文件，省卻了手工配置的麻煩。基本上，在Doxywizard中可以完成Doxygen的絕大多數(shù)工作，而且Doxygen也可以在由Doxywizard啟動(dòng)，這樣就使得整個(gè)過程比較連貫。
雖然如此，我們還是要理解常見的各個(gè)Tag的含義。在Doxywizard中，可以看到這些Tag以自明的方式命名，我們大致可以從名稱中看出其作用。這些Tag被Doxywizard大致分為幾類，其中HTML到PerlMod是輸出文件種類設(shè)置，Project是Doxygen工程設(shè)置，Build是編譯類選項(xiàng)，Messages為出錯(cuò)或異常選項(xiàng)，Input為輸入源選項(xiàng)，等等。
圖2 Doxywizard
注釋
Doxygen規(guī)定了進(jìn)行注釋的一些格式，正確的注釋才能使Doxygen生成文檔。第一個(gè)代碼條目，都有兩種描述：簡(jiǎn)要描述和詳細(xì)描述，兩者都是可選的。簡(jiǎn)要描述只有一行，而詳細(xì)描述則提供更長(zhǎng)、更仔細(xì)的描述，Doxygen只允許有一個(gè)簡(jiǎn)要描述和詳細(xì)描述。
在Doxygen中，一般只會(huì)處理與程序結(jié)構(gòu)相關(guān)的注釋，函數(shù)內(nèi)部的注釋通常不做處理。對(duì)于詳細(xì)描述來說，有下面幾種表示方式。
JavaDoc風(fēng)格，中間的"*"號(hào)可選。/*** 注釋*/Qt風(fēng)格，中間的"*"號(hào)可選。/*!* 注釋*/C++風(fēng)格的變體，或者最后一個(gè)"/"改為"！"也可以。/// 單行注釋/// 注釋///更加顯著的表示。////////////////////////////////////////////// 注釋///////////////////////////////////////////簡(jiǎn)要描述亦有多種表示方式。在上述注釋塊中使用\brief命令，詳細(xì)注釋在空行之后開始。/*! \brief 簡(jiǎn)要描述* 繼續(xù)** 詳細(xì)注釋*/JAVADOC_AUTOBRIEF設(shè)置為YES后，在JavaDoc風(fēng)格的注釋中，第一個(gè)點(diǎn)號(hào)之前的內(nèi)容被自動(dòng)設(shè)置為簡(jiǎn)要描述。對(duì)于多行C++變體，這個(gè)選項(xiàng)亦會(huì)起到相同的作用。/** 簡(jiǎn)要描述.詳細(xì)描述* 注釋*/C++變體風(fēng)格。/// 簡(jiǎn)要描述/* 詳細(xì)描述 */
命令
Doxygen支持的指令非常多，主要作用是控制輸出文檔的排版格式。命令以"\"或"@"號(hào)開始。
一些命令可以有多個(gè)參數(shù)，一些命令只有一個(gè)參數(shù)。參數(shù)周圍的括號(hào)使用是有含義的：
- <>號(hào)表示參數(shù)是單個(gè)詞。
- ()號(hào)表示參數(shù)一直會(huì)到行尾。
- {}號(hào)表示參數(shù)會(huì)擴(kuò)展到下一段落。
- []號(hào)表示參數(shù)是可選的。
下面章節(jié)中也涉及到一些命令的使用，其它的命令可以查閱Doxygen用戶手冊(cè)。
列表
Doxygen有許多方法可以創(chuàng)建項(xiàng)目列表。
使用"-"在每行開始之前打頭，使用"."可以結(jié)束一個(gè)列表，開始新的段落。使用這種方法要嚴(yán)格對(duì)齊。/*** - 表項(xiàng)一* - 子項(xiàng)一* - 子項(xiàng)二* .* .*/在文檔塊中使用HTML命令。這種方法不需要嚴(yán)格對(duì)齊。/*!* <ul>* <li> 表項(xiàng)一* <ol>* <li> 子項(xiàng)一* <li> 子項(xiàng)二* </ol>* <li> 表項(xiàng)二* </ul>*/
|
分組
Doxygen有兩種分組機(jī)制。第一種是全局地為每一個(gè)組創(chuàng)建一個(gè)網(wǎng)頁，此時(shí)分組被稱為"module"；第二種是用于復(fù)合實(shí)體中的成員列表，此時(shí)分組被稱為"member group"。Module是一種把內(nèi)容在單個(gè)網(wǎng)頁上分組的方法。分組可以包括files，namespace，classes，functions，variables，enums，typedefs和defines，也可以包含其它分組。復(fù)合實(shí)體（compound entities）如類、文件、命名空間等可以分布在多個(gè)分組中，而成員實(shí)體（member）如變量、函數(shù)、typedef等只能歸屬于一個(gè)分組。
定義分組的方法是在特殊注釋塊中使用命令\defgroup和\addtogroup。 defgroup的格式如下：
\defgroup <唯一標(biāo)識(shí)名> （中間可以有空格的標(biāo)題）
兩次使用同一標(biāo)識(shí)名，在doxygen解析的時(shí)候會(huì)出現(xiàn)錯(cuò)誤。命令addtogroup與defgroup不同的地方在于，如果使用了同一標(biāo)識(shí)，則會(huì)在改組中加入新的項(xiàng)，如果標(biāo)識(shí)不重復(fù)，則會(huì)創(chuàng)建分組。addtogroup中的標(biāo)題是可選的。
聲明分組之后，如果要使某個(gè)實(shí)體歸屬某一分組，需要使用ingroup命令。避免在每個(gè)成員之前都使用ingroup命令，可以將member用@{和@}封裝起來。
/** * \ingroup A */extern int VarInA;/** * \defgroup IntVariables Global integer variables *//*@{*//** an integer variable */extern int IntegerVariable;/*@}*/..../** * \defgroup Variables Global variables *//*@{*//** a variable in group A */int VarInA;int IntegerVariable;/*@}*/
|
上面這些命令都是有優(yōu)先級(jí)的，doxygen會(huì)根據(jù)優(yōu)先級(jí)將實(shí)體放入具有最高優(yōu)先級(jí)的分組之中。它們的優(yōu)先級(jí)順序是：ingroup，defgroup，addtogroup，weakgroup。weakgroup類似一個(gè)低優(yōu)先級(jí)的addtogroup。在.h文件中可以使用高優(yōu)先級(jí)的命令定義層次結(jié)構(gòu)，在.c文件中\(zhòng)weakgroup就不需要準(zhǔn)確遵循.h文件中定義的層次結(jié)構(gòu)。
如果要把不同的類型歸入同一分組內(nèi)，就要使用Member group，它的定義方法如下：
//@{ ...//@}或者/*@{*/ ... /*@}*/
|
Member group不可以嵌套。
圖表
Doxygen里有內(nèi)置生成C++類層次圖的功能。它使用貝爾實(shí)驗(yàn)室開發(fā)的graphviz 1.5中的工具"dot"來生成更高級(jí)的圖表。使用這個(gè)工具時(shí)，要將配置選項(xiàng)HAVE_DOT設(shè)為YES。
- 當(dāng)GRAPHICAL_HIERARCHY設(shè)置為YES時(shí)，將會(huì)繪制一個(gè)圖形表示的類圖結(jié)構(gòu)。
- 當(dāng)CLASS_GRAPH設(shè)置為YES時(shí)，會(huì)為每個(gè)歸檔的類創(chuàng)建一張圖表示其直接或間接的繼承關(guān)系。
- 當(dāng)INCLUDE_GRAPH設(shè)置為YES時(shí)，會(huì)為每個(gè)歸檔文件創(chuàng)建一幅包含依賴圖，此功能目前僅有HTML和RTF格式支持。
- 當(dāng)COLLABORATION_GRAPH設(shè)置為YES時(shí)，會(huì)為每個(gè)歸檔類或結(jié)構(gòu)繪制基類繼承關(guān)系圖和使用關(guān)系圖。
- 當(dāng)CALL_GRAPH設(shè)置為YES時(shí)，會(huì)為每個(gè)函數(shù)顯示一幅直接或間接調(diào)用關(guān)系圖。
更具體的信息可以參考Doxygen的手冊(cè)。
公式
Doxygen可以把LaTeX格式的公式輸出出來。要在HTML文檔里包含公式，需要安裝下面的工具：latex（LaTeX編譯器）、dvips（將DVI文件轉(zhuǎn)換為PS文件）、gs（將PS文件轉(zhuǎn)換為位圖）。
包含公式的方法有兩種：
使用\f$命令對(duì)表示文本中間的公式，遵循LaTeX格式。\f$(x_1, y_1)\f$ (x1,y1)位于獨(dú)立一行上未編號(hào)的公式，應(yīng)放在命令\f[和\f]之間。\f[ |I_2|=\left| \psi(t) \right|\f]對(duì)應(yīng)的輸出是|I2|=|ψ(t)|。
|
中文文檔
Doxygen支持多種語言，輸出中文文檔的時(shí)候，只需要將配置文件中的OUTPUT_LANGUAGE標(biāo)簽設(shè)置為Chinese即可（用Doxywizard修改更方便）。
有一個(gè)需要注意的問題是，在Windows下的瀏覽器瀏覽中文HTML文檔時(shí)，英文字母會(huì)變得很難看，解決的辦法是將doxygen_cn.css下載到本地硬盤，并將配置文件中的HTML_STYLESHEET修改為這個(gè)文件的位置。
HTML_STYLESHEET=c:\doxygen\doxygen.css
運(yùn)行doxygen
在命令行下運(yùn)行doxygen是很簡(jiǎn)單的，只需要指定配置文件即可。
doxygen project.cfg
或者，也可以使用Doxywizard在配置完后直接運(yùn)行doxygen。
|