如果您這次還沒來得及使用老式的Help Workshop為您的Web應用構建文檔系統的話那麼何不嘗試一下Doxygen需知The proof of the pudding lies in the eating
Doxygen是什麼？
Doxygen是一種開源跨平台的以類似JavaDoc風格描述的文檔系統完全支持CC++JavaObjectiveC和IDL語言部分支持PHPC#注釋的語法與QtDocKDoc和JavaDoc兼容Doxgen可以從一套歸檔源文件開始生成HTML格式的在線類浏覽器或離線的LATEXRTF參考手冊對於未歸檔的源文件也可以通過配置Doxygen來提取代碼結構或者借助自動生成的包含依賴圖（include dependency graphs）繼承圖（inheritance diagram）以及協作圖（collaboration diagram）來可視化文檔之間的關系Doxygen生成的幫助文檔的格式可以是CHMRTFPostScriptPDFHTML和Unix man page等
Doxygen在Linux上開發但也可以在其它的Unix平台下運行而且Windows x/NT平台下也有對應的可執行版本
安裝Doxygen
首先去Doxygen網站上找到最新版本的Doxygen有二進制或源碼兩種版本如果不想重頭編譯下載二進制版本安裝即可在Linux下源碼編譯需要perl和Gnu工具flexbisonmake的支持在Windows下二進制版本勿需安裝而源碼編譯所需支持工具較多我們僅講述Linux下的Doxygen的源碼編譯以及二進制版本安裝過程
編譯源碼
gunzip doxygen$VERSIONsrctargz
tar xf doxygen$VERSIONsrctar
sh /configure或者configure platform platformtype
（略去直接使用configure需要平台檢測的過程平台類型在PLATFORMS文件中列出）
configure withdoxywizard（GUI前端選項）
make或者make docs（創建HTML格式的手冊）make pdf（創建PDF格式的手冊）
安裝二進制版本
/configure
make install
二進制文件安裝目錄是<prefix>/bin其中<prefix>缺省為/usr可以通過configure的參數prefix修改其值使用make install_docs可以把文檔和例子安裝在目錄<docdir>/doxygen其中<docdir>缺省為<prefix>/share/doc/packages可以通過configure的參數docdir修改其值doxygen是bin目錄下的一個命令行程序它是Doxygen的核心工具完成文檔的轉換和生成工作
Doxygen的處理流程
圖是Doxygen網站上給出的Doxygen處理工具以及它們之間的信息流
從圖中可以看出Doxygen可執行程序位於正中所有的流程都圍繞著它進行左側圖標表示Doxygen的輸入可以是源文件或者是定制的頭文件圖像注解等Doxygen圖標上部是配置文件由Doxywizard處理下部是Tag文件由Doxytag處理後面是Doxygen輸出文件的類型依次是XMLLatexMan pagesRTF和HTML可處理類型圖標之後是進行進一步轉換所需的工具
圖 Doxygen網站上給出的Doxygen信息流圖
配置文件
每一個Doxygen工程都有一個後綴為cfg的配置文件用來保存所有的設置配置文件的格式與autoexecbatconfigsys等文件相似是由名稱/值對組成的ASCII碼會由doxygen命令來解析為了簡化創建和修改配置文件Doxygen可以在命令行方式下加上參數g自動創建模板文件
doxygen g <configfile>
忽略<configfile>將會生成一個名為Doxyfile的缺省文件如果<configfile>已經存在會被Doxygen改名為<configfile>bak
實際上我們根本就不需要用一般的編輯器來編輯配置文件Doxygen提供了一個輔助工具DoxywizardDoxywizard是Doxygen的GUI前台用戶可以能過它來讀寫配置文件省卻了手工配置的麻煩基本上在Doxywizard中可以完成Doxygen的絕大多數工作而且Doxygen也可以在由Doxywizard啟動這樣就使得整個過程比較連貫
雖然如此我們還是要理解常見的各個Tag的含義在Doxywizard中可以看到這些Tag以自明的方式命名我們大致可以從名稱中看出其作用這些Tag被Doxywizard大致分為幾類其中HTML到PerlMod是輸出文件種類設置Project是Doxygen工程設置Build是編譯類選項Messages為出錯或異常選項Input為輸入源選項等等
圖 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 groupModule是一種把內容在單個網頁上分組的方法分組可以包括filesnamespaceclassesfunctionsvariablesenumstypedefs和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會根據優先級將實體放入具有最高優先級的分組之中它們的優先級順序是ingroupdefgroupaddtogroupweakgroupweakgroup類似一個低優先級的addtogroup在h文件中可以使用高優先級的命令定義層次結構在c文件中\weakgroup就不需要准確遵循h文件中定義的層次結構
如果要把不同的類型歸入同一分組內就要使用Member group它的定義方法如下
//@{
//@}
或者
/*@{*/
/*@}*/
Member group不可以嵌套
圖表
Doxygen裡有內置生成C++類層次圖的功能它使用貝爾實驗室開發的graphviz 中的工具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_ y_)\f$ (xy)
位於獨立一行上未編號的公式應放在命令\f[和\f]之間
\f[
|I_|=\left| \psi(t)
\right|
\f]
對應的輸出是|I|=|ψ(t)|
中文文檔
Doxygen支持多種語言輸出中文文檔的時候只需要將配置文件中的OUTPUT_LANGUAGE標簽設置為Chinese即可（用Doxywizard修改更方便）
有一個需要注意的問題是在Windows下的浏覽器浏覽中文HTML文檔時英文字母會變得很難看解決的辦法是將doxygen_cncss下載到本地硬盤並將配置文件中的HTML_STYLESHEET修改為這個文件的位置
HTML_STYLESHEET=c:\doxygen\doxygencss
運行doxygen
在命令行下運行doxygen是很簡單的只需要指定配置文件即可
doxygen projectcfg
或者也可以使用Doxywizard在配置完後直接運行doxygen
圖 doxygen的輸出示例
From:http://tw.wingwit.com/Article/program/Java/hx/201311/26448.html
