1簡介

Doxygen 是一個程式的檔案產生工具，可將程式中的特定批註轉換成為說明檔案。通常我們在寫程式時，或多或少都會寫上批註，但是對於其它人而言，要直接探索程式裡的批註，與打撈泰坦尼克號同樣的辛苦。大部分有用的批註都是屬於針對函式，類別等等的說明。所以，如果能依據程式本身的結構，將批註經過處理重新整理成為一個純粹的參考手冊，對於後面利用您的程式程式碼的人而言將會減少許多的負擔。不過，反過來說，整理檔案的工作對於您來說，就是沉重的負擔。 對於未歸檔的原始檔，也可以通過配置Doxygen來提取程式碼結構。或者藉助自動生成的包含依賴圖（includedependency graphs）、繼承圖（inheritance diagram）以及

協作圖（collaborationdiagram）來視覺化文件之間的關係。Doxygen生成的幫助文件的格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。 一個好的程式設計師，在寫程式時，都會在適當的地方加上合適的批註。如果，能夠在撰寫批註時，稍微符合某種格式，接著就可以透過一個工具程式依據程式結構及您的批註產生出漂亮的檔案。這將令許多工作繁重的程式設計師有時間多喝幾杯咖啡。 Doxygen 就是這樣的一個工具。在您寫批註時，稍微按照一些它所制訂的規則。接著，他就可以幫您產生出漂亮的檔案了。因此，Doxygen 的使用可分為兩大部分。首先是特定格式的批註撰寫，第二便是利用Doxygen的工具來產生檔案。

2程式語言

* C/C++ * Java * Objective-C * Python * IDL (Corba, Microsoft及KDE-DCOP型別) * Fortran * VHDL * PHP * C#

3檔案格式

* HTML * XML * LaTeX * RTF (MS-Word) * PostScript * Unix Man Page 而其中還可衍生出不少其它格式。如有了LaTeX 檔案後，就可以透過一些工具產生出PS或是PDF檔案。 在多國語言的支援方面，Doxygen 目前可支援的約有2,30種。自Doxygen 1.2.16開始支援繁體中文(這正是小弟做的好事)。所以在目前一些Open Source 的

程式文件管理器中，Doxygen 算是相當完整的一套。在程式語言處理上面，Doxygen也算是少數在Borland C++Builder 的語法下還能夠正常運作的工具之一（若非如此，小弟也不會推薦它）。 本文的目的是希望在經過仔細閱讀本文之後能夠給大家一個概略性的瞭解。以便可以很容易的上手使用Doxygen。至於Doxygen本身的詳細使用，各位可以參考隨著Doxygen 所附的檔案。實際上，Doxygen 自己的使用手冊就是使用Doxygen 產生的。您可以看到他實際上能夠產生遠比Reference Book更復雜的檔案。

4安裝

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出現。

5組態

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檔案。

6使用步驟

由於只是工具的使用，這裡不介紹它的原理，直接從使用步驟開始。Doxygen的使用步驟非常簡單。主要可以分為： 1）第一次使用需要安裝doxygen的程式 2）生成doxygen配置檔案 3）編碼時，按照某種格式編寫註釋 4）生成對應文件 doxygen的安裝非常簡單， linux下可以直接下載安裝包執行即可，下載原始碼編譯安裝也是比較通用的編譯安裝命令。請參考其安裝文件完成安裝。 Doxygen在生成文件時可以定義專案屬性以及文件生成過程中的很多選項，使用下面命令能夠產生一個預設的配置檔案： doxygen -g [配置檔名] 可以根據專案的具體需求修改配置檔案中對應的項，具體的修改過程在下面介紹。修改過的配置檔案可以作為以後專案的模板。 讓doxygen自動產生文件，平常的註釋風格可不行，需要遵循doxygen自己的格式。具體如何寫doxygen認識的註釋在第3節詳細介紹。 OK，程式碼編完了，註釋也按照格式寫好了，最後的文件是如何的哪？非常簡單，執行下面的命令，相應的文件就會產生在指定的目錄中。 doxygen [配置檔名] 需要注意的是doxygen並不處理所有的註釋，doxygen重點關注與程式結構有關的註釋，比如：檔案、類、結構、函式、變數、巨集等註釋，而忽略函式內變數、程式碼等的註釋。

7配置檔案

doxygen配置檔案的格式是也是通常的unix下配置檔案的格式：註釋'#'開始；tag = value [,value2…]；對於多值的情況可以使用 tag += value [,value2…]。 對doxygen的配置檔案的修改分為兩類：一種就是輸出選項，控制如何解釋原始碼、如何輸出；一種就是專案相關的資訊，比如專案名稱、原始碼目 錄、輸出文件目錄等。對於第一種設定好後，通常所有專案可以共用一份配置，而後一種是每個專案必須設定的。下面選擇重要的，有可能需要修改的選項進行解釋 說明，其他選項在配置檔案都有詳細解釋。 TAG 預設值 含義 PROJECT_NAME 專案名稱 PROJECT_NUMBER 可以理解為版本資訊 OUTPUT_DIRECTORY 輸出檔案到的目錄，相對目錄（doxygen執行目錄）或者絕對目錄 INPUT 程式碼檔案或者程式碼所在目錄，使用空格分割 FILE_PATTERNS *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl 指定INPUT的目錄中特定檔案，如：*.cpp *.c *.h RECURSIVE NO 是否遞迴INPUT中目錄的子目錄 EXCLUDE 在INPUT目錄中需要忽略的子目錄 EXCLUDE_PATTERNS 明確指定的在INPUT目錄中需要忽略的檔案，如：FromOut*.cpp OUTPUT_LANGUAGE English 生成文件的語言，當前支援2、30種語言，國內使用者可以設定為Chinese USE_WINDOWS_ENCODING YES（win版本） NO（unix版本） 編碼格式，預設即可。 EXTRACT_ALL NO 為NO，只解釋有doxygen格式註釋的程式碼；為YES，解析所有程式碼，即使沒有註釋。類的私有成員和所有的靜態項由EXTRACT_PRIVATE和 EXTRACT_STATIC控制 EXTRACT_PRIVATE NO 是否解析類的私有成員 EXTRACT_STATIC NO 是否解析靜態項 EXTRACT_LOCAL_CLASSES YES 是否解析原始檔（cpp檔案）中定義的類 SOURCE_BROWSER NO 如果為YES，原始碼檔案會被包含在文件中 INLINE_SOURCES NO 如果為YES，函式和類的實現程式碼被包含在文件中 ALPHABETICAL_INDEX NO 生成一個字母序的列表，有很多類、結構等項時建議設為YES GENERATE_HTML YES 是否生成HTML格式文件 GENERATE_HTMLHELP NO 是否生成壓縮HTML格式文件（.chm） GENERATE_LATEX YES 是否生成latex格式的文件 GENERATE_RTF NO 是否生成RTF格式的文件 GENERATE_MAN NO 是否生成man格式文件 GENERATE_XML NO 是否生成XML格式文件

8註釋

3.1 註釋風格

下面是工作量最大部分，安照doxygen格式寫註釋。通常程式碼可以附上一個註釋塊來對 程式碼進行解釋，一個註釋塊由一行或者多行組成。通常一個註釋塊包括一個簡要說明（brief）和一個詳細說明（detailed），這兩部分都是可選的。 可以有多種方式標識出doxygen可識別的註釋塊。 1）JavaDoc型別的多行註釋。 2）QT樣式的多行註釋。 3） /// …text…. 4） //! …text…. 簡要說明有多種方式標識，這裡推薦使用@brief命令強制說明，例如： 以上這些註釋格式用來對緊跟其後的程式碼進行註釋。doxygen也允許把註釋放到程式碼後面，具體格式是放一個'<'到註釋開始部分。例如： int var1 ; int var2; ///< ….text…. 註釋和程式碼完全分離，放在其他地方也是允許的，但需要使用特殊的命令加上名稱或者宣告進行標識，比如：class、struct、union、 enum、fn、var、def、file、namespace、package、interface（這些也就是doxygen關注的註釋型別）。這裡 不推薦使用，建議註釋儘量放在程式碼前後。具體使用方式參見doxygen手冊。

3.2 doxygen常用註釋格式

通常的選擇上面的一、兩種註釋風格，遇到標頭檔案中各種型別定義，關鍵變數、巨集的定義，在其前或者後使用 @brief 定義其簡要說明，空一行後繼續寫其詳細的註釋即可。 對函式的註釋，是比較常常需要註釋的部分。除了定義其簡要說明以及詳細註釋，還可以使用param命令對其各個引數進行註釋，使用return命令對返回值進行註釋。常見的格式如下： int func1(int a, int b); 進行設計時，通常有模組的概念，一個模組可能有多個類或者函式組成，完成某個特定功能的程式碼的集合。如何對這個概念進行註釋？doxygen提供了group的概念，生成的模組的註釋會單獨放在一個模組的頁面中。使用下面的格式定義一個group。 code group中的程式碼可以有自己的註釋。單純定義一個模組，去除{ 和}命令即可。任何其他程式碼項（比如類、函式、甚至檔案）如果要加入到某個模組，可以在其doxygen註釋中使用ingroup命令即可。Group之間使用ingroup命令，可以組成樹狀關係。 把多個程式碼項一起新增到某個模組中可以使用addtogroup命令，格式和defgroup相似。 對於某幾個功能類似的程式碼項（比如類、函式、變數）等，如果希望一起添加註釋，而又不想提升到模組的概念，可以通過下面的方式： //@{ code… //@} 對這種組進行命名可以使用name命令。此時中間程式碼可以有自己的註釋。如： //@{ code… //@}

3.3 doxygen常用註釋命令

doxygen通過註釋命令識別註釋中需要特殊處理的註釋，比如函式的引數、返回值進行突出顯示。上面也提到了一些註釋命令（如：brief、param、return、以及group相關的命令），下面對其他一些常用的註釋命令進行解釋說明。 @exception <exception-object> {exception description} 對一個異常物件進行註釋。 @warning {warning message } 一些需要注意的事情 @todo { things to be done } 對將要做的事情進行註釋 @see {comment with reference to other items } 一段包含其他部分引用的註釋，中間包含對其他程式碼項的名稱，自動產生對其的引用連結。 @relates <name> 通常用做把非成員函式的註釋文件包含在類的說明文件中。 @since {text} 通常用來說明從什麼版本、時間寫此部分程式碼。 @deprecated @pre { description of the precondition } 用來說明程式碼項的前提條件。 @post { description of the postcondition } 用來說明程式碼項之後的使用條件。 @code 在註釋中開始說明一段程式碼，直到@endcode命令。 @endcode 註釋中程式碼段的結束。 到此為止，常用的doxygen的註釋格式討論完畢，我們能夠按照一定的格式撰寫doxygen認識的註釋，並能夠使用doxygen方便快捷的生成對應的文件，不過註釋中應該寫些什麼，如何撰寫有效的註釋可能是困擾開發人員的一個更深層次的問題。

4. 註釋的書寫

註釋應該怎麼寫，寫多還是寫少。過多的註釋甚至會干擾對程式碼的閱讀。寫註釋的一個總的原則就是註釋應該儘量用來表明作者的 意圖，至少也應該是對一部分程式碼的總結，而不應該是對程式碼的重複或者解釋。對程式碼的重複或者解釋的程式碼，看程式碼可能更容易理解。反映作者意圖的註釋解釋代 碼的目的，從解決問題的層次上進行註釋，而程式碼總結性註釋則是從問題的解答的層次上進行註釋。 推薦的寫註釋的過程是首先使用註釋勾勒出程式碼的主要框架，然後根據註釋撰寫相應的程式碼。對各種主要的資料結構、輸出的函式、多個函式公用的變數進行詳細地註釋。對程式碼中控制結構，單一目的的語句集進行註釋。下面是一些寫註釋時需要注意的要點： 避免對單獨語句進行註釋； 通過註釋解釋為什麼這麼做、或者要做什麼，使程式碼的讀者可以只閱讀註釋理解程式碼； 對讀者可能會有疑問的地方進行註釋； 對資料定義進行註釋，而不是對其使用過程進行註釋； 對於難於理解的程式碼，進行改寫，而不要試圖通過註釋加以說明； 對關鍵的控制結構進行註釋； 對資料和函式的邊界、使用前提等進行註釋；

9建立檔案

當您前面所有的步驟都正確無誤執行後，只需要執行下面的命令就可建立出您要的檔案了： > doxygen Doxygen 如果有錯誤產生，請檢查您的Doxygen 組態檔設定是否有誤，目錄的存取許可權是否足夠。如果輸出的結果不正確，請檢查您的批註是否符合格式。批註的位置是否正確。舉例來說，您不可在說明class的批註與class 本身插入其它的程式程式碼或宣告。否則Doxygen 就無法將批註與該class對應起來。 如果您使用Doxygen Wizard，可直接使用上面的Run 的按鈕或選單專案來製作說明檔案。如果是產生HTML檔案，在HTML_OUTPUT 所指定的目錄中的index.html將是您說明檔案的首頁。 在中文繁體方面，目前我僅成功製作出HTML與RTF 格式的說明檔案。其它格式的過程比較複雜，需要搭配其它工具，有待各位自行嘗試。

10版本

2012年12月28日，Doxygen 1.8.3 釋出，文件生成工具^[1]