使用doxygen
（已發表在《程序員》2002年第3期上）
一、介紹
GLAST軟件已采用doxygen（GNU GPL軟件）來作為文檔工具，本文將對其進行簡單的介紹。要了解更詳細的信息及下載doxygen程序，請訪問網站http://www.stack.nl/~dimitri/doxygen/。
什麽是doxygen呢？下麵的介紹錄自doxygen的網頁：
“doxygen是一種用於C++、IDL（Corba、Microsoft和KDE-2 DCOP風格）和C的文檔係統。它可以通過三種方式來幫助你：
1. 它可以從一組標有文檔的源文件中生成在線文檔瀏覽器（HTML格式），以及/或者離線參考手冊（LATEX格式）。同時還支持生成RTF（MS-Word）、Postscript、超鏈接PDF、壓縮HTML和UNIX man頁麵格式的輸出。文檔是從源文件中直接提取的，從而十分容易保持文檔和源碼的一致。
2. 可配置doxygen，用以從沒有標注文檔的源文件中提取代碼結構。這對於要在大量源文件中快速地找到所需的東西來說是非常有用的。通過include依賴圖、繼承圖和協作圖等手段（它們都是自動生成的），可以使不同成分之間的關係可視化。
3. 你甚至還可以“濫用”doxygen，創建普通文檔。”
二、doxygen注釋風格
使用doxygen的第一步是在你的代碼中插入doxygen風格的注釋。你可以使用兩種不同風格的doxygen注釋：
- Qt風格，專用文檔塊看起來是這樣的：
/*!
... text ...
*/
還有單行版本：
file://! ... one line of text ... - JavaDoc風格，專用文檔塊看起來是這樣的：
/**
* ... text ...
*/
還有單行版本：
/// ... one line of text ...
從現在起我將在例子中使用Qt風格，但是你可以在你的代碼中使用任何一種。
你可以通過許多方式使用doxygen注釋，以為你的代碼編寫文檔。但下麵的一種，我們感覺能夠令人滿意地工作。注意下麵的注解僅僅說明應該如何使用doxygen注釋；你所應該包含在注釋裏的信息是另外一回事，並不在這裏進行討論。
我們的基本想法是你想要為每個類、以及該類的重要成員函數增加短注釋和長注釋。短注釋應給出類或函數的基本信息的簡要描述。而較長的注釋，不奇怪，應該給出更長和更完整的描述。類的短注釋和長注釋，以及成員函數的簡短描述，將放在頭文件中。成員函數的長注釋將出現在成員函數的實現出現的地方。
下麵的例子演示這一注釋係統（向Alexandre、Regis和Jose道歉，我在此過程中“黑”了他們的代碼）。假定我們正在為一種叫作CalPack 的CMT包工作，它有一個單獨的類CsICluster，頭文件叫作CsICluster.h，在CalPack/目錄中；而實現文件叫作CsICluster.cpp，在src/目錄中。文件CalPack/CsICluster.h是這樣的：
而文件src/CsICluster.cpp是這樣的：
注意，你可能會選擇省略那些含義清楚的成員函數的較長注釋，這並不會導致任何問題。訪問http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v1/class_CsICluster.html可以看到上麵被注釋的代碼所產生的HTML文檔。
三、使用mainpage.h文件
瀏覽上麵的鏈接中的文檔，你可能會注意到名為“Main Page”的鏈接（它指向index.html）並不是十分有趣。這是一個特殊的頁麵，在這裏你可以添加與你的doxygen頁麵描述的所有類有關的文檔。在我們的例子中隻有一個單獨的類，但是你可以使用doxygen來處理如你所選擇的那麽多的類。一種自然的劃分是為每一個GLAST CMT包都創建doxygen頁麵。於是合乎想像地，我們想要這個主頁麵成為對正在被討論的包的描述；在我們的個案中就是CalPack包。
那麽我們怎麽為此主頁麵增添內容呢？你需要使用doxygen的特殊命令mainpage。在doxygen中有一些特殊命令，它們放在doxygen注釋中以增強你所生成的文檔。例如在類描述中，我們已經使用了doxygen特殊命令author。
命令mainpage指定用以填充主頁麵的注釋的內容。doxygen允許你將此命令放在任何注釋中。但是，GLAST的慣例是將該命令放入文件mainpage.h中。這個mainpage.h文件應該隻包含一條使用mainpage命令的注釋。並且這個文件應該放在頭文件目錄中，也就是，與包自己的名字相同的目錄。
於是我們為CalPack包創建一個CalPack/mainpage.h文件：
注意在mainpage命令後麵的字句是主頁麵的標題。我們還引入了section命令，其語法你應該可以推論得出。上麵的注釋所產生的HTML輸出見http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v2/。你還可以在此訪問CsICluster類的文檔。
四、包含圖像
另一個有趣的命令（對此我們希望實施某種標準）是image命令。此命令用於在你的文檔中插入圖像。image命令可以用在任何注釋中。此命令的語法如下所示：
image html mypicture.gif
盡管我們僅僅顯示了HTML輸出，doxygen還可以用於創建latex、man或rtf文檔。但是，並非所有格式都支持所有的圖像類型。因而，有必要指定你所希望在其中包含的圖像的輸出格式。doxygen將在你通過叫作IMAGE_PATH的變量所指定的目錄中查找圖像文件。對此變量的設置以及其他的doxygen缺省值將在下麵的“運行doxygen”中解釋。目前，隻需注意GLAST的慣例是在你的文檔中為給定的包所使用的全部圖像文件都將放在叫作doc/images/的目錄中。
於是假設有一個叫作figuresim2.gif的圖像文件在目錄doc/images/中，我們想要將其插入我們的主頁麵，我們可以通過簡單的改動來完成：
所產生的HTML輸出見http://www.slac.stanford.edu/exp/glast/ground/software/doxygen_examples/v3/。
五、運行doxygen
你可以通過兩種方式來運行doxygen。注意兩種方法都需要你將doxygen安裝在你的訪問路徑上。請訪問doxygen的主頁以獲得下載和設置可執行程序的相關信息。
1) 對於vcmt用戶，你可以簡單地點擊doxygen區域中的“create”按鈕，從而為你選擇的所有包創建HTML文檔。然後點擊“examine”來查看頁麵。
2) 對於非vcmt用戶，你首先需要創建一個Doxyfile。Doxyfile允許你設置運行doxygen所需的所有設置和路徑。要創建Doxyfile，執行
doxygen –g
● INPUT：此參數指定doxygen在其中搜索源碼的目錄。對於上麵的例子，需要設置
INPUT = src CalPack
● FILE_PATTERNS：此參數指定doxygen所要解析的文件的類型。對於上麵的例子，
需要設置
FILE_PATTERNS = *.cpp *.h
● IMAGE_PATH：此參數指定doxygen在哪裏查找使用image命令包含的圖像。對
於上麵的例子（並且作為GLAST的慣例），需要設置
INCLUDE_PATH = doc/images
一旦你設置了這些參數以及其他任何你想要改變的參數，你就可以運行doxygen了。假定你的Doxyfile就叫作“Doxyfile”，執行
doxygen Doxyfile
它將解析你指定的所有文件。缺省地，HTML輸出將被放在叫作html/的目錄中（這也可以在Doxyfile中改變）。
譯者注：
1. doxygen有內建的多語言支持，目前支持24種語言，其中包括中文。具體用法請參考doxygen的參考手冊。
2. GLAST是The Gamma Ray Large Area Space Telescope（伽瑪射線大區域空間望遠鏡）的縮寫。主頁在http://www-glast.stanford.edu/，可通過CVS訪問其源碼。
