牽著老婆滿街逛

嚴以律己,寬以待人. 三思而后行.
GMail/GTalk: yanglinbo#google.com;
MSN/Email: tx7do#yahoo.com.cn;
QQ: 3 0 3 3 9 6 9 2 0 .

統計

隨筆 - 1513
文章 - 45
評論 - 907
引用 - 0

公告

言論：
1.每日自??；
2.享受人生；
3.盡力而為；
4.堅持不懈；
5.切莫急躁；
6.慎言敏行；
7.動心忍性；
8.上善若水。

常用鏈接

留言簿(11)

隨筆分類(466)

隨筆檔案(1513)

文章分類(46)

文章檔案(45)

相冊

收藏夾(39)

搜索

積分與排名

積分 - 2523560
排名 - 2

閱讀排行榜

使用doxygen

?撰文/K.Young?????????翻譯/馬維達

（已發表在《程序員》2002年第3期上）

一、介紹

GLAST軟件已采用doxygen（GNUGPL軟件）來作為文檔工具，本文將對其進行簡單的介紹。要了解更詳細的信息及下載doxygen程序，請訪問網站什么是doxygen呢？下面的介紹錄自doxygen的網頁：

“doxygen是一種用于C++、IDL（Corba、Microsoft和KDE-2DCOP風格）和C的文檔系統。它可以通過三種方式來幫助你：

1.???????它可以從一組標有文檔的源文件中生成在線文檔瀏覽器（HTML格式），以及/或者離線參考手冊（LATEX格式）。同時還支持生成RTF（MS-Word）、Postscript、超鏈接PDF、壓縮HTML和UNIXman頁面格式的輸出。文檔是從源文件中直接提取的，從而十分容易保持文檔和源碼的一致。

2.?????可配置doxygen，用以從沒有標注文檔的源文件中提取代碼結構。這對于要在大量源文件中快速地找到所需的東西來說是非常有用的。通過include依賴圖、繼承圖和協作圖等手段（它們都是自動生成的），可以使不同成分之間的關系可視化。

3.?????你甚至還可以“濫用”doxygen，創建普通文檔。”

二、doxygen注釋風格

使用doxygen的第一步是在你的代碼中插入doxygen風格的注釋。你可以使用兩種不同風格的doxygen注釋：

Qt風格，專用文檔塊看起來是這樣的：
/*!
...text...
*/

還有單行版本：
file://!...onelineoftext...JavaDoc風格，專用文檔塊看起來是這樣的：
/**
?*...text...
?*/

還有單行版本：
///...onelineoftext...

從現在起我將在例子中使用Qt風格，但是你可以在你的代碼中使用任何一種。

你可以通過許多方式使用doxygen注釋，以為你的代碼編寫文檔。但下面的一種，我們感覺能夠令人滿意地工作。注意下面的注解僅僅說明應該如何使用doxygen注釋；你所應該包含在注釋里的信息是另外一回事，并不在這里進行討論。

我們的基本想法是你想要為每個類、以及該類的重要成員函數增加短注釋和長注釋。短注釋應給出類或函數的基本信息的簡要描述。而較長的注釋，不奇怪，應該給出更長和更完整的描述。類的短注釋和長注釋，以及成員函數的簡短描述，將放在頭文件中。成員函數的長注釋將出現在成員函數的實現出現的地方。

下面的例子演示這一注釋系統（向Alexandre、Regis和Jose道歉，我在此過程中“黑”了他們的代碼）。假定我們正在為一種叫作CalPack的CMT包工作，它有一個單獨的類CsICluster，頭文件叫作CsICluster.h，在CalPack/目錄中；而實現文件叫作CsICluster.cpp，在src/目錄中。文件CalPack/CsICluster.h是這樣的：

而文件src/CsICluster.cpp是這樣的：

注意，你可能會選擇省略那些含義清楚的成員函數的較長注釋，這并不會導致任何問題。訪問文檔。

三、使用mainpage.h文件

瀏覽上面的鏈接中的文檔，你可能會注意到名為“MainPage”的鏈接（它指向index.html）并不是十分有趣。這是一個特殊的頁面，在這里你可以添加與你的doxygen頁面描述的所有類有關的文檔。在我們的例子中只有一個單獨的類，但是你可以使用doxygen來處理如你所選擇的那么多的類。一種自然的劃分是為每一個GLASTCMT包都創建doxygen頁面。于是合乎想像地，我們想要這個主頁面成為對正在被討論的包的描述；在我們的個案中就是CalPack包。

那么我們怎么為此主頁面增添內容呢？你需要使用doxygen的特殊命令\mainpage。在doxygen中有一些特殊命令，它們放在doxygen注釋中以增強你所生成的文檔。例如在類描述中，我們已經使用了doxygen特殊命令\author。

命令\mainpage指定用以填充主頁面的注釋的內容。doxygen允許你將此命令放在任何注釋中。但是，GLAST的慣例是將該命令放入文件mainpage.h中。這個mainpage.h文件應該只包含一條使用\mainpage命令的注釋。并且這個文件應該放在頭文件目錄中，也就是，與包自己的名字相同的目錄。

于是我們為CalPack包創建一個CalPack/mainpage.h文件：

注意在\mainpage命令后面的字句是主頁面的標題。我們還引入了\section命令，其語法你應該可以推論得出。上面的注釋所產生的HTML輸出見類的文檔。

四、包含圖像

另一個有趣的命令（對此我們希望實施某種標準）是\image命令。此命令用于在你的文檔中插入圖像。\image命令可以用在任何注釋中。此命令的語法如下所示：

\imagehtmlmypicture.gif

盡管我們僅僅顯示了HTML輸出，doxygen還可以用于創建latex、man或rtf文檔。但是，并非所有格式都支持所有的圖像類型。因而，有必要指定你所希望在其中包含的圖像的輸出格式。doxygen將在你通過叫作IMAGE_PATH的變量所指定的目錄中查找圖像文件。對此變量的設置以及其他的doxygen缺省值將在下面的“運行doxygen”中解釋。目前，只需注意GLAST的慣例是在你的文檔中為給定的包所使用的全部圖像文件都將放在叫作doc/images/的目錄中。

于是假設有一個叫作figuresim2.gif的圖像文件在目錄doc/images/中，我們想要將其插入我們的主頁面，我們可以通過簡單的改動來完成：

所產生的HTML輸出見五、運行doxygen

你可以通過兩種方式來運行doxygen。注意兩種方法都需要你將doxygen安裝在你的訪問路徑上。請訪問doxygen的主頁以獲得下載和設置可執行程序的相關信息。

1)??????對于vcmt用戶，你可以簡單地點擊doxygen區域中的“create”按鈕，從而為你選擇的所有包創建HTML文檔。然后點擊“examine”來查看頁面。

2)????對于非vcmt用戶，你首先需要創建一個Doxyfile。Doxyfile允許你設置運行doxygen所需的所有設置和路徑。要創建Doxyfile，執行

doxygen–g<filename>

“filename”指定含有doxygen設置的文件的名字；如果不指定名字，該文件就叫作“Doxyfile”。使用Doxyfile時你可能想要設置一些參數。我將提及三個有趣的參數，其他的請參考doxygen主頁。

●INPUT：此參數指定doxygen在其中搜索源碼的目錄。對于上面的例子，需要設置

??INPUT=srcCalPack

●FILE_PATTERNS：此參數指定doxygen所要解析的文件的類型。對于上面的例子，
??需要設置

??FILE_PATTERNS=*.cpp*.h

●IMAGE_PATH：此參數指定doxygen在哪里查找使用\image命令包含的圖像。對
??于上面的例子（并且作為GLAST的慣例），需要設置

??INCLUDE_PATH=doc/images

一旦你設置了這些參數以及其他任何你想要改變的參數，你就可以運行doxygen了。假定你的Doxyfile就叫作“Doxyfile”，執行

doxygenDoxyfile

它將解析你指定的所有文件。缺省地，HTML輸出將被放在叫作html/的目錄中（這也可以在Doxyfile中改變）。

譯者注：

1.???????doxygen有內建的多語言支持，目前支持24種語言，其中包括中文。具體用法請參考doxygen的參考手冊。

2.?????GLAST是TheGammaRayLargeAreaSpaceTelescope（伽瑪射線大區域空間望遠鏡）的縮寫。主頁在訪問其源碼。/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT:7PT'TIMESNEWROMAN'">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="MARGIN-LEFT:18PT;TEXT-INDENT:-18PT;WORD-BREAK:BREAK-ALL">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="MARGIN-LEFT:18PT;TEXT-INDENT:-18PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="MARGIN-LEFT:18PT;TEXT-INDENT:-18PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/LICLASS=MSONORMALSTYLE="MARGIN-BOTTOM:12PT;TEXT-ALIGN:LEFT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="MARGIN-LEFT:18PT;TEXT-INDENT:-18PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT:7PT'TIMESNEWROMAN'">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT:7PT'TIMESNEWROMAN'">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PCLASS=MSONORMALSTYLE="TEXT-INDENT:21PT;WORD-BREAK:BREAK-ALL">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/PALIGN=CENTERCLASS=MSONORMALSTYLE="TEXT-ALIGN:CENTER;TEXT-INDENT:42PT">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">/SPANSTYLE="FONT-FAMILY:楷體_GB2312">

posted on 2006-07-19 22:18 楊粼波閱讀(1301) 評論(0) 編輯收藏引用所屬分類: 學習筆記

只有注冊用戶登錄后才能發表評論。
【推薦】100%開源！大型工業跨平臺軟件C++源碼提供，建模，組態！

相關文章: CxImage使用掩碼色設置透明色的圖 MFC獲取窗口可視狀態的兩種API方法 IsWindowVisible無法獲取到正確的狀態？基于Dialog程序,啟動時不顯示主窗口,只顯示子窗口的實現絕對好用 Linux操作系統的8個經典技巧 Putty相關的知識 Vim7中的Tab功能犯了一個最愚蠢的錯誤=.= 有關MFC的C1189錯誤的解決一些DX的資源

網站導航: 博客園 IT新聞 BlogJava 博問 Chat2DB 管理

青青草原综合久久大伊人导航_色综合久久天天综合_日日噜噜夜夜狠狠久久丁香五月_热久久这里只有精品

牽著老婆滿街逛

導航

統計

公告

常用鏈接

留言簿(11)

隨筆分類(466)

隨筆檔案(1513)

文章分類(46)

文章檔案(45)

相冊

收藏夾(39)

工具官網

技術網站

開源網站

其他窩點

收藏網站

銀行官網

友情鏈接

資源共享

搜索

積分與排名

最新評論

閱讀排行榜

使用doxygen