使用Doxygen構建文檔系統

作者：車皓陽

作者簡介

車皓陽，您可以通過grandiose11@msn.com和作者取得聯系。

正文

如果您這次還沒來得及使用老式的Help Workshop為您的Web應用構建文檔系統的話，那么，何不嘗試一下Doxygen，需知"The proof of the pudding lies in the eating"。

Doxygen是什么？

Doxygen是一種開源跨平臺的，以類似JavaDoc風格描述的文檔系統，完全支持C、C++、Java、Objective-C和IDL語言，部分支持PHP、C#。注釋的語法與Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以從一套歸檔源文件開始，生成HTML格式的在線類瀏覽器，或離線的LATEX、RTF參考手冊。對于未歸檔的源文件，也可以通過配置Doxygen來提取代碼結構?；蛘呓柚詣由傻陌蕾噲D（include dependency graphs）、繼承圖（inheritance diagram）以及協作圖（collaboration diagram）來可視化文檔之間的關系。Doxygen生成的幫助文檔的格式可以是CHM、RTF、PostScript、PDF、HTML和Unix man page等。

Doxygen在Linux上開發，但也可以在其它的Unix平臺下運行。而且，Windows 9x/NT平臺下也有對應的可執行版本。

安裝Doxygen

首先，去Doxygen網站上找到最新版本的Doxygen。有二進制或源碼兩種版本，如果不想重頭編譯，下載二進制版本安裝即可。在Linux下，源碼編譯需要perl和Gnu工具flex、bison、make的支持。在Windows下，二進制版本勿需安裝，而源碼編譯所需支持工具較多。我們僅講述Linux下的Doxygen的源碼編譯以及二進制版本安裝過程。

編譯源碼

gunzip doxygen-$VERSION.src.tar.gztar xf doxygen-$VERSION.src.tarsh ./configure，或者configure --platform platform-type（略去直接使用configure需要平臺檢測的過程，平臺類型在PLATFORMS文件中列出），configure --with-doxywizard（GUI前端選項）make，或者make docs（創建HTML格式的手冊），make pdf（創建PDF格式的手冊）

安裝二進制版本

./configuremake install

二進制文件安裝目錄是<prefix>/bin，其中<prefix>缺省為/usr，可以通過configure的參數--prefix修改其值。使用make install_docs可以把文檔和例子安裝在目錄<docdir>/doxygen，其中<docdir>缺省為<prefix>/share/doc/packages，可以通過configure的參數--docdir修改其值。doxygen是bin目錄下的一個命令行程序，它是Doxygen的核心工具，完成文檔的轉換和生成工作。

Doxygen的處理流程

圖1是Doxygen網站上給出的Doxygen處理工具以及它們之間的信息流。

從圖中可以看出，Doxygen可執行程序位于正中，所有的流程都圍繞著它進行。左側圖標表示Doxygen的輸入可以是源文件，或者是定制的頭文件、圖像、注解等。Doxygen圖標上部是配置文件，由Doxywizard處理，下部是Tag文件，由Doxytag處理。后面是Doxygen輸出文件的類型，依次是XML、Latex、Man pages、RTF和HTML，可處理類型圖標之后是進行進一步轉換所需的工具。

javascript:window.open(this.src);" style="CURSOR: pointer" onload="return imgzoom(this,550)">

圖1  Doxygen網站上給出的Doxygen信息流圖

配置文件

每一個Doxygen工程都有一個后綴為.cfg的配置文件，用來保存所有的設置。配置文件的格式與autoexec.bat、config.sys等文件相似，是由名稱/值對組成的ASCII碼，會由doxygen命令來解析。為了簡化創建和修改配置文件，Doxygen可以在命令行方式下加上參數-g自動創建模板文件。

doxygen -g <config-file>

忽略<config-file>將會生成一個名為Doxyfile的缺省文件，如果<config-file>已經存在，會被Doxygen改名為<config-file>.bak。

實際上，我們根本就不需要用一般的編輯器來編輯配置文件，Doxygen提供了一個輔助工具Doxywizard。Doxywizard是Doxygen的GUI前臺，用戶可以能過它來讀寫配置文件，省卻了手工配置的麻煩?；旧?，在Doxywizard中可以完成Doxygen的絕大多數工作，而且Doxygen也可以在由Doxywizard啟動，這樣就使得整個過程比較連貫。

雖然如此，我們還是要理解常見的各個Tag的含義。在Doxywizard中，可以看到這些Tag以自明的方式命名，我們大致可以從名稱中看出其作用。這些Tag被Doxywizard大致分為幾類，其中HTML到PerlMod是輸出文件種類設置，Project是Doxygen工程設置，Build是編譯類選項，Messages為出錯或異常選項，Input為輸入源選項，等等。

圖2  Doxywizard

注釋

Doxygen規定了進行注釋的一些格式，正確的注釋才能使Doxygen生成文檔。第一個代碼條目，都有兩種描述：簡要描述和詳細描述，兩者都是可選的。簡要描述只有一行，而詳細描述則提供更長、更仔細的描述，Doxygen只允許有一個簡要描述和詳細描述。

在Doxygen中，一般只會處理與程序結構相關的注釋，函數內部的注釋通常不做處理。對于詳細描述來說，有下面幾種表示方式。

JavaDoc風格，中間的"*"號可選。/*** 注釋*/Qt風格，中間的"*"號可選。/*!* 注釋*/C++風格的變體，或者最后一個"/"改為"！"也可以。/// 單行注釋/// 注釋///更加顯著的表示。////////////////////////////////////////////// 注釋///////////////////////////////////////////簡要描述亦有多種表示方式。在上述注釋塊中使用\brief命令，詳細注釋在空行之后開始。/*! \brief 簡要描述*繼續** 詳細注釋*/ JAVADOC_AUTOBRIEF設置為YES后，在JavaDoc風格的注釋中，第一個點號之前的內容被自動設置為簡要描述。對于多行C++變體，這個選項亦會起到相同的作用。/** 簡要描述.詳細描述* 注釋*/C++變體風格。/// 簡要描述/* 詳細描述 */

命令

Doxygen支持的指令非常多，主要作用是控制輸出文檔的排版格式。命令以"\"或"@"號開始。

一些命令可以有多個參數，一些命令只有一個參數。參數周圍的括號使用是有含義的：

• <>號表示參數是單個詞。
• ()號表示參數一直會到行尾。
• {}號表示參數會擴展到下一段落。
• []號表示參數是可選的。

下面章節中也涉及到一些命令的使用，其它的命令可以查閱Doxygen用戶手冊。

列表

Doxygen有許多方法可以創建項目列表。

使用"-"在每行開始之前打頭，使用"."可以結束一個列表，開始新的段落。使用這種方法要嚴格對齊。/***  - 表項一*    - 子項一*    - 子項二*   .*  .*/在文檔塊中使用HTML命令。這種方法不需要嚴格對齊。/*!*  <ul>* <li> 表項一*<ol>*     <li> 子項一*     <li> 子項二*    </ol>*  <li> 表項二*  </ul>*/

分組

Doxygen有兩種分組機制。第一種是全局地為每一個組創建一個網頁，此時分組被稱為"module"；第二種是用于復合實體中的成員列表，此時分組被稱為"member group"。Module是一種把內容在單個網頁上分組的方法。分組可以包括files，namespace，classes，functions，variables，enums，typedefs和defines，也可以包含其它分組。復合實體（compound entities）如類、文件、命名空間等可以分布在多個分組中，而成員實體（member）如變量、函數、typedef等只能歸屬于一個分組。

定義分組的方法是在特殊注釋塊中使用命令\defgroup和\addtogroup。 defgroup的格式如下：

\defgroup <唯一標識名> （中間可以有空格的標題）

兩次使用同一標識名，在doxygen解析的時候會出現錯誤。命令addtogroup與defgroup不同的地方在于，如果使用了同一標識，則會在改組中加入新的項，如果標識不重復，則會創建分組。addtogroup中的標題是可選的。

聲明分組之后，如果要使某個實體歸屬某一分組，需要使用ingroup命令。避免在每個成員之前都使用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;/*@}*/

上面這些命令都是有優先級的，doxygen會根據優先級將實體放入具有最高優先級的分組之中。它們的優先級順序是：ingroup，defgroup，addtogroup，weakgroup。weakgroup類似一個低優先級的addtogroup。在.h文件中可以使用高優先級的命令定義層次結構，在.c文件中\weakgroup就不需要準確遵循.h文件中定義的層次結構。

如果要把不同的類型歸入同一分組內，就要使用Member group，它的定義方法如下：

//@{   ...//@}或者/*@{*/   ... /*@}*/

Member group不可以嵌套。

圖表

Doxygen里有內置生成C++類層次圖的功能。它使用貝爾實驗室開發的graphviz 1.5中的工具"dot"來生成更高級的圖表。使用這個工具時，要將配置選項HAVE_DOT設為YES。

• 當GRAPHICAL_HIERARCHY設置為YES時，將會繪制一個圖形表示的類圖結構。
• 當CLASS_GRAPH設置為YES時，會為每個歸檔的類創建一張圖表示其直接或間接的繼承關系。
• 當INCLUDE_GRAPH設置為YES時，會為每個歸檔文件創建一幅包含依賴圖，此功能目前僅有HTML和RTF格式支持。
• 當COLLABORATION_GRAPH設置為YES時，會為每個歸檔類或結構繪制基類繼承關系圖和使用關系圖。
• 當CALL_GRAPH設置為YES時，會為每個函數顯示一幅直接或間接調用關系圖。

更具體的信息可以參考Doxygen的手冊。

公式

Doxygen可以把LaTeX格式的公式輸出出來。要在HTML文檔里包含公式，需要安裝下面的工具：latex（LaTeX編譯器）、dvips（將DVI文件轉換為PS文件）、gs（將PS文件轉換為位圖）。

包含公式的方法有兩種：

使用\f$命令對表示文本中間的公式，遵循LaTeX格式。\f$(x_1, y_1)\f$(x1,y1)位于獨立一行上未編號的公式，應放在命令\f[和\f]之間。\f[    |I_2|=\left| \psi(t)           \right|\f]對應的輸出是|I2|=|ψ(t)|。

中文文檔

Doxygen支持多種語言，輸出中文文檔的時候，只需要將配置文件中的OUTPUT_LANGUAGE標簽設置為Chinese即可（用Doxywizard修改更方便）。

有一個需要注意的問題是，在Windows下的瀏覽器瀏覽中文HTML文檔時，英文字母會變得很難看，解決的辦法是將doxygen_cn.css下載到本地硬盤，并將配置文件中的HTML_STYLESHEET修改為這個文件的位置。

HTML_STYLESHEET=c:\doxygen\doxygen.css

運行doxygen

在命令行下運行doxygen是很簡單的，只需要指定配置文件即可。

doxygen project.cfg

或者，也可以使用Doxywizard在配置完后直接運行doxygen。

圖3  doxygen的輸出示例

原文轉自：http://www.kjueaiud.com