| ||||||
| 便利的开发文档工具-doxygen 0. 序言 Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统 上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目（包括前两篇文章介绍的log4cpp和CppUnit）都使用了doxygen文档系统。而国内的开发人员却使用的不 多，这里从开发人员使用的角度介绍这个工具，使开发人员用最少的代价尽快掌握这种技术，并结合这个工具探讨如何撰写注释的问题。以下以linux下的C+ +语言为例进行介绍，以下讨论基于doxygen1.3.3。 1. doxygen使用步骤 Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件： 让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。具体如何写doxygen认识的注释在第3节详细介绍。 OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪？非常简单，运行下面的命令，相应的文档就会产生在指定的目录中。 需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。 2. doxygen配置文件 对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目 录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释 说明，其他选项在配置文件都有详细解释。 TAG 缺省值 含义 3. doxygen注释 注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、 enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里 不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。 3.2 doxygen常用注释格式 对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下： 进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。 对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式： 3.3 doxygen常用注释命令 到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。 4. 注释的书写 推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点： 5. 参考资料 2. doxygen manual 3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4. 6. 使用doxygen | ||||||
簡介Doxygen
什麼是Doxygen?
Doxygen 是一個程式的文件產生工具，可將程式中的特定註解轉換成為說明文件。通常我們在寫程式時，或多或少都會寫上註解，但是對於其他人而言，要直接探索程式裡的 註解，與打撈鐵達尼號同樣的辛苦。大部分有用的註解都是屬於針對函式，類別等等的說明。所以，如果能依據程式本身的結構，將註解經過處理重新整理成為一個 純粹的參考手冊，對於後面利用您的程式碼的人而言將會減少許多的負擔。不過，反過來說，整理文件的工作對於您來說，就是沈重的負擔。一個好的程式設計師，在寫程式時，都會在適當的地方加上合適的註解。如果，能夠在撰寫註解時，稍微符合某種格式，接著就可以透過一個工具程式依據程式結構及您的註解產生出漂亮的文件。這將令許多工作繁重的程式設計師有時間多喝幾杯咖啡。
Doxygen 就是這樣的一個工具。在您寫註解時，稍微按照一些它所制訂的規則。接著，他就可以幫您產生出漂亮的文件了。因此，Doxygen 的使用可分為兩大部分。首先是特定格式的註解撰寫，第二便是利用Doxygen的工具來產生文件。
目前Doxygen可處理的程式語言包含：
- C/C++
- Java
- IDL (Corba, Microsoft及KDE-DCOP類型)
- HTML
- XML
- LaTeX
- RTF
- Unix Man Page
在多國語言的支援方面，Doxygen 目前可支援的約有2,30種。自Doxygen 1.2.16開始支援繁體中文(這正是小弟做的好事)。所以在目前一些Open Source 的程式文件產生器中，Doxygen 算是相當完整的一套。在程式語言處理上面，Doxygen也算是少數在Borland C++ Builder 的語法下還能夠正常運作的工具之一（若非如此，小弟也不會推薦它）。
本文的目的是希望在經過仔細閱讀本文之後能夠給大家一個概略性的瞭解。以便可以很容易的上手使用Doxygen。至於Doxygen本身的詳細使用，各位可以參考隨著Doxygen 所附的文件。實際上，Doxygen 自己的使用手冊就是使用Doxygen 產生的。您可以看到他實際上能夠產生遠比Reference Book更複雜的文件。
安裝Doxygen
Doxygen 的安裝可說十分的簡單，本文僅介紹binary檔案的安裝，若您有興趣從source code重新compile起來，請自行查閱參考手冊。首先，請您先至 doxygen 的網站上面抓取最新版本的doxygen 回來。目前，只要您是Linux, Solaris, Mac OS X, HP-UX, 甚至是UnixWare，都有compile好的binary版本可以抓取。如果是Windows 95/98/ME/NT/2000/XP，甚至還有Setup的版本可以抓取。所以安裝過程可說十分簡單。只要給予正確的安裝目錄，相信一般在安裝上是不會遇到什麼問題的。
另外，如果您是Linux或是Windows，可以另外抓取Doxygen Wizard的程式。這是一個輔助工具，可以很快的幫您建立一個Doxygen 的組態檔案。透過這個組態檔案，您就可以很快的將文件產生出來。另外，若沒有使用Doxygen Wizard，還是可以使用一般的文字編輯器將這個組態檔製作出來。
若安裝成功，您應該可以看到doxygen 這個執行檔出現在您的系統中。若是Windows 平台，則可看到在程式集中有Doxygen 這個Folder出現。
設定Project的doxygen組態
Doxygen 產生文件可以分為三個步驟。一是為Project 建立組態檔，二是在程式碼中加上符合Doxygen所定義註解格式。三是使用Doxygen來產生註解。因此，第一步就是為您的Project 製作Doxygen 的組態檔案。這個所謂的組態檔案，格式其實與很簡單。就是一些Key 與值的設定。每個設定為一行。若第一行開頭為"#" 表示該行為註解。Doxygen 會忽略它。每個設定行的格式有兩種，分別如下：
TAG = value [value, ...]及
TAG += value [value, ...]第一種形式是最常見的，也就是要設定一個TAG (也就是一個Key )，他的值為右邊所定義的部分。原則上每個值都是單一的英文字，如果您要定義的值有空白字元包含在內，可使用雙引號將它括住。如果要定義的值超過一個以上，可使用逗號","予以分隔開來。
如果您要定義的TAG 是屬於表列型態的，也就是他會有很多的值分別以逗號隔開。在Doxygen 組態檔中允許您在不同的地方重複定義。只是後面的定義應使用上面所說的第二種形式。此種形式會將前後兩個定義的值合併在一起。
知道這個基本格式後，剩下就是根據各個TAG 的意義來進行設定。關於TAG 的定義很多，此處我們僅針對必要用到的TAG 進行說明，剩下的部分請自行翻閱使用說明。
由於Doxygen 的TAG 還算不少，為了方便使用，Doxygen 自身提供了一個方便的選項，可以幫您建立一份空白的Doxygen檔案(Doxygen 是Doxygen 預設的組態檔名)。
> doxygen Doxygen
透過這個命令，您可以得到一個Doxygen 檔案，接下來就可使用一般的文字編輯器來進行編輯。
下面將針對幾個必要的TAG 進行說明：
| PROJECT_NAME | Project 的名字，以一個單字為主，多個單字請使用雙引號括住。 |
| PROJECT_VERSION | Project的版本號碼。 |
| OUTPUT_DIRECTORY | 輸出路徑。產生的文件會放在這個路徑之下。如果沒有填這個路徑，將會以目前所在路徑來作為輸出路徑。 |
| OUTPUT_LANGUAGE | 輸出語言。預設為English。1.2.16 版後，您可以使用Chinese-Traditional 來輸出中文繁體的格式。 |
| INPUT | 指定載入或找尋要處理的程式碼檔案路徑。這邊是一個表列式的型態。並且可指定檔案及路徑。舉例來說若您有a.c, b.c, c.c 三個檔案。您可使用INPUT = a.c, b.c, c.c 的方式。若您給定一個目錄，該目錄下面所有檔案都會被處理。 |
| FILE_PATTERNS | 如果您的INPUT Tag 中指定了目錄。您可以透過這個Tag來要求Doxygen在處理時，只針對特定的檔案進行動作。例如：您希望對目錄下的副檔名為.c, .cpp及.h的檔案作處理。您可設定FILE_PATTERNS = *.c, *.cpp, *.h。 |
| RECURSIVE | 這是一個布林值的Tag，只接受YES或NO。當設定為YES時，INPUT所指定目錄的所有子目錄都會被處理。 |
| EXCLUDE | 如果您有某幾個特定檔案或是目錄，不希望經過Doxygen處理。您可在這個Tag中指定。 |
| EXCLUDE_PATTERNS | 類似於FILE_PATTERNS的用法，只是這個Tag是供EXCLUDE所使用。 |
| SOURCE_BROWSER | 如果設定為YES，則Doxygen會產生出原始檔案的列表，以供查閱。 |
| INLINE_SOURCES | 如果設定為YES ，則程式碼也會被嵌入於說明文件中。 |
| ALPHABETICAL_INDEX | 如果設定為YES，則一個依照字母排序的列表會加入在產生的文件中。 |
| GENERATE_HTML | 若設定為YES ，就會產生HTML版本的說明文件。HTML文件是Doxygen預設產生的格式之一。 |
| HTML_OUTPUT | HTML文件的輸出目錄。這是一個相對路徑，所以實際的路徑為OUTPUT_DIRECTORY加上HTML_OUTPUT。這個設定預設為html。 |
| HTML_FILE_EXTENSION | HTML文件的副檔名。預設為.html。 |
| HTML_HEADER | 要使用在每一頁HTML文件中的Header。如果沒有指定，Doxygen會使用自己預設的Header。 |
| HTML_FOOTER | 要使用在每一頁HTML文件中的Footer。如果沒有指定，Doxygen會使用自己預設的Footer。 |
| HTML_STYLESHEET | 您可給定一個CSS 的設定，讓HTML的輸出結果更完美。 |
| GENERATE_HTMLHELP | 如設定為YES，Doxygen會產生一個索引檔。這個索引檔在您需要製作windows 上的HTML格式的HELP檔案時會用的上。 |
| GENERATE_TREEVIEW | 若設定為YES，Doxygen會幫您產生一個樹狀結構，在畫面左側。這個樹狀結構是以JavaScript所寫成。所以需要新版的Browser才能正確顯示。 |
| TREEVIEW_WIDTH | 用來設定樹狀結構在畫面上的寬度。 |
| GENERATE_LATEX | 設定為YES 時，會產生LaTeX 的文件。不過您的系統必需要有安裝LaTeX 的相關工具。 |
| LATEX_OUTPUT | LaTeX文件的輸出目錄，與HTML_OUTPUT用法相同，一樣是指在OUTPUT_DIRECTORY之下的路徑。預設為latex。 |
| LATEX_CMD_NAME | LaTeX程式的命令名稱及檔案所在。預設為latex。 |
| GENERATE_RTF | 若設定為YES ，則會產生RTF 格式的說明檔。 |
| RTF_OUTPUT | 與HTML_OUTPUT 用法相同，用來指定RTF 輸出檔案路徑。預設為rtf。 |
| GENERATE_MAN | 若設定為YES ，則會產生Unix Man Page 格式的說明文件。 |
| MAN_OUTPUT | 與HTML_OUTPUT 用法相同，用來指定Man Page的輸出目錄。預設為man。 |
| GENERATE_XML | 若設定為YES ，則會產生XML 格式的說明文件。 |
| ENABLE_PREPROCESSING | 若設定為YES ，則Doxygen 會啟動C 的前置處理器來處理原始檔。 |
| PREDEFINED | 可以讓您自行定義一些巨集。類似於gcc 中的-D選項。 |
若上面這些基本的Tag 都設定正確，接下來就是將您的Source Code
註解修改成為正確的格式。若您覺得用一般文字編輯器來編輯組態檔
很麻煩，建議您可以使用Doxygen Wizard這個工具程式。他可以很快
的建構出您所需要的Doxygen檔案。
撰寫正確格式的註解
並非所有程式碼中的註解都會被Doxygen 所處理。您必需依照正確的格式撰寫。原則上，Doxygen 僅處理與程式結構相關的註解，如
Function，Class ，檔案的註解等。對於Function內部的註解則不做
處理。Doxygen可處理下面幾種類型的註解。
JavaDoc類型：
/**
* ... 註解 ...
*/
Qt類型：
/*!
* ... 註解 ...
*/
單行型式的註解：
/// ... 註解 ...或
//! ... 註解 ...
要使用哪種型態完全看自己的喜好。以筆者自己來說，大範圍的註
解我會使用JavaDoc 型的。單行的註解則使用"///" 的類型。
此外，由於Doxygen 對於註解是視為在解釋後面的程式碼。也就是
說，任何一個註解都是在說明其後的程式碼。如果要註解前面的程
式碼則需用下面格式的註解符號。
/*!< ... 註解 ... */
/**< ... 註解 ... */
//!< ... 註解 ...
///< ... 註解 ...
上面這個方式並不適用於任何地方，只能用在class 的member或是
function的參數上。
舉例來說，若我們有下面這樣的class。
class MyClass {
public:
int member1 ;
int member2:
void member_function();
};
加上註解後，就變成這樣：
/**
* 我的自訂類別說明 ...
*/
class MyClass {
public:
int member1 ; ///< 第一個member說明 ...
int member2: ///< 第二個member說明 ...
int member_function(int a, int b);
};
/**
* 自訂類別的member_funtion說明 ...
*
* @param a 參數a的說明
* @param b 參數b的說明
*
* @return 傳回a+b。
*/
int MyClass::member_function( int a, int b )
{
return a+b ;
}
當您使用Doxygen 產生說明文件時，Doxygen 會幫您parsing 您的程
式碼。並且依據程式結構建立對應的文件。然後再將您的註解，依據
其位置套入於正確的地方。您可能已經注意到，除了一般文字說明外
，還有一些其他特別的指令，像是@param及@return 等。這正是
Doxygen 另外一個重要的部分，因為一個類別或是函式其實都有固定
幾個要說明的部分。為了讓Doxygen 能夠判斷，所有我們就必需使用
這些指令，來告訴Doxygen 後面的註解是在說明什麼東西。Doxygen
在處理時，就會幫您把這些部分做特別的處理或是排版。甚至是製作
參考連結。
首先，我們先說明在Doxygen 中對於類別或是函數註解的一個特定格
式。
/**
* class或function的簡易說明...
*
* class或function的詳細說明...
* ...
*/
上面這個例子要說的是，在Doxygen 處理一個class 或是function註
解時，會先判斷第一行為簡易說明。這個簡易說明將一直到空一行的
出現。或是遇到第一個"." 為止。之後的註解將會被視為詳細說明。
兩者的差異在於Doxygen 在某些地方只會顯示簡易說明，而不顯示詳
細說明。如：class 或function的列表。
另一種比較清楚的方式是指定@brief的指令。這將會明確的告訴
Doxygen，何者是簡易說明。例如：
/**
* @brief class或function的簡易說明...
*
* class或function的詳細說明...
* ...
*/
除了這個class 及function外，Doxygen 也可針對檔案做說明，條件
是該註解需置於檔案的前面。主要也是利用一些指令，通常這部分註
解都會放在檔案的開始地方。如：
/*! /file myfile.h
/brief 檔案簡易說明
詳細說明.
/author 作者資訊
*/
如您所見，檔案註解約略格式如上，請別被"/" 所搞混。其實，"/"
與"@" 都是一樣的，都是告訴Doxygen 後面是一個指令。兩種在
Doxygen 都可使用。筆者自己比較偏好使用"@"。
接著我們來針對一些常用的指令做說明：
| @file | 檔案的註解說明。 |
| @author | 作者的資訊 |
| @brief | 用於class 或function的註解中，後面為class 或function的簡易說明。 |
| @param | 格式為@param arg_name 參數說明主要用於函式說明中，後面接參數的名字，然後再接關於該參數的說明。 |
| @return | 後面接函數傳回值的說明。用於function的註解中。說明該函數的傳回值。 |
| @retval | 格式為@retval value 傳回值說明主要用於函式說明中，說明特定傳回值的意義。所以後面要先接一個傳回值。然後在放該傳回值的說明。 |
Doxygen 所支援的指令很多，有些甚至是關於輸出排版的控制。您可從Doxygen的使用說明中找到詳盡的說明。
下面我們準備一組example.h 及example.cpp 來說明Doxygen 註解的使用方式：
example.h:
/**
* @file 本範例的include檔案。
*
* 這個檔案只定義example這個class。
*
* @author garylee@localhost
*/
#define EXAMPLE_OK 0 ///< 定義EXAMPLE_OK的巨集為0。
/**
* @brief Example class的簡易說明
*
* 本範例說明Example class。
* 這是一個極為簡單的範例。
*
*/
class Example {
private:
int var1 ; ///< 這是一個private的變數
public:
int var2 ; ///< 這是一個public的變數成員。
int var3 ; ///< 這是另一個public的變數成員。
void ExFunc1(void);
int ExFunc2(int a, char b);
char *ExFunc3(char *c) ;
};
example.cpp:
/**
* @file 本範例的程式碼檔案。
*
* 這個檔案用來定義example這個class的
* member function。
*
* @author garylee@localhost
*/
/**
* @brief ExFunc1的簡易說明
*
* ExFunc1沒有任何參數及傳回值。
*/
void Example::ExFunc1(void)
{
// empty funcion.
}
/**
* @brief ExFunc2的簡易說明
*
* ExFunc3()傳回兩個參數相加的值。
*
* @param a 用來相加的參數。
* @param b 用來相加的參數。
* @return 傳回兩個參數相加的結果。
*/
int ExFunc2(int a, char b)
{
return (a+b);
}
/**
* @brief ExFunc3的簡易說明
*
* ExFunc3()只傳回參數輸入的指標。
*
* @param c 傳進的字元指標。
* @retval NULL 空字串。
* @retval !NULL 非空字串。
*/
char * ExFunc2(char * c)
{
return c;
}
上面這兩個檔案很簡單的說明了Doxygen 註解的使用方式。您可依照此要領在你自己的程式碼中加上對應的註解。其實，無論您有無使用Doxygen ，都不妨依照他的格式將註解寫入，一方面是依照他的格式，並不會干擾您程式的運作。另一方面，Doxygen 所定義的都是基本程式註解應當要有的東西。撰寫清楚的註解是好的程式設計師應當的工作。
製作說明文件
當您前面所有的步驟都正確無誤執行後，只需要執行下面的命令就可建立出您要的文件了：> doxygen Doxygen
如果有錯誤產生，請檢查您的Doxygen 組態檔設定是否有誤，目錄的存取權限是否足夠。如果輸出的結果不正確，請檢查您的註解是否符合格式。註解的位置是否正確。舉例來說，您不可在說明class 的註解與class 本身插入其他的程式碼或宣告。否則Doxygen 就無法將註解與該class對應起來。
如果您使用Doxygen Wizard，可直接使用上面的Run 的按鈕或選單項目來製作說明文件。如果是產生HTML文件，在HTML_OUTPUT 所指定的目錄中的index.html將是您說明文件的首頁。
在中文繁體方面，目前我僅成功製作出HTML與RTF 格式的說明文件。其他格式的過程比較複雜，需要搭配其他工具，有待各位自行嘗試。
Special Commands In Homepage:
804
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
