為了找類似 Javadoc 的工具給 C++用,而發現了 Doxygen ,然後他的好處並不只限於產出文件檔,我非常喜歡拿產出的文件檔來 Trace Code,因為它產出的文件檔不只附上了原始碼(Source Code)還具有超連結,可以很方便的在函數、變數進行上下頁切換,先簡介一下這個好東西在給大家看現成的範例。
安裝Doxygen
先到 Doxygen網站下載最新的版本,依照你的作業系統進行安裝
程式碼註解
Doxygen 支援 Java 與 QT 的註解形式,因此單行註解可以寫成
/// ... 註解 ...
//! ... 註解 ...
多行註解可以寫成
/**
*...註解...
*/
/*!
*...註解...
*/
設定Project組態
Doxygen 是靠著一個組態檔在進行文件產出的,而組態檔也只是一個純文字檔,靠著Tag, Value的方式進行設定,以下介紹幾個必要的Tag,其他若有興趣可以上 Doxygen官網查詢。
http://www.stack.nl/%7Edimitri/doxygen/doxygen_intro_cn.htmlPROJECT_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 所指定目錄的所有子目錄都會被處理。 & amp; nbsp; |
EXCLUDE | 如果您有某幾個特定檔案或是目錄,不希望經過Doxygen處理。您可在這個 Tag中指定。 |
EXCLUDE_PATTERNS | 類似於FILE_PATTERNS的用法,只是這個 Tag是供EXCLUDE所使用。 |
SOURCE_BROWSER | 如果設定為YES,則Doxygen會產生出原始檔案的列表,以供查閱。 |
INLINE_SOURCES | 如果設定為YES ,則程式碼也會被嵌入於說明文件中。 & amp; nbsp; |
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。& nbsp; |
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 的前置處理器來處理原始檔。 & nbsp; |
PREDEFINED | 可以讓您自行定義一些巨集。類似於gcc 中的-D選項。 |
實際範例
以好用的文字編輯軟體 NotePad++ 為例
在Project Label的地方輸入如下
Build Label就看你想要產出的文件檔需要有什麼樣的功能作選擇,以我個人而言除了一些HIDE的屬性全部勾選
Input Label的部份選擇原始碼的來源,Source Browser Label勾選如下就會將你的原始碼一併放到文件中囉!
再來就是設定一些產出的文件類型,這邊我以 HTML 為例,當然 Doxygen 也可以產生成 Windows Help,不過我還是覺得產出 HTML 效果最好,現在大家可以來看一下產出文件的結果了。