日期 |
修訂版本 |
描述 |
作者 |
2009-05-11 |
0.0.1 |
初稿 |
溫陵布衣 |
1 概述
1.1 簡介
本節以Doxygen-1.6.2爲例,介紹該工具的概貌。
Ø 功能:將源碼中的註釋提取出來,形成各種輸出格式的文檔;
Ø 支持的編程語言:完全支持 C、C++、Java、IDL、Objective-C、Python、PHP、C#、Fortran、VHDL,部分支持D;
Ø 輸出格式:直接支持 HTML、Latex、RTF、manpage、Qt help project、XML,間接支持 chm、Qt Compressed Help、Postcript和PDF;
Ø 兼容 JavaDoc、Qt-Doc、KDOC等類似工具;
Ø 支持平臺:Unix(包括Linux)、MacOs、Windows等;
郵件列表:
Ø 作者:Dimitri van Heesch ([email protected]) ;
Ø 參考手冊:Doxygen 安裝目錄下的參考手冊;
1.2 能完成的工作
Ø 它能從一系列源文件中生成在線瀏覽文檔(HTML形式)或離線參考手冊(LATEX形式)。還支持RTF(MS-Word),PostScript,帶超鏈接的PDF,壓縮的HTML和Unix man頁。文檔是直接從源文件中提取出來的,這使得文檔與源代碼很容易保持同步;
Ø 通過配置doxygen,你可以從未文檔化的源文件中提取出代碼結構。這對於從大的源碼包中快速理清頭緒是非常有用的。它還能自動產生出包含關係圖、繼承圖和協作圖,使你能直觀地看出各種元素間的關係;
Ø 你甚至可以“濫用“doxygen來創建平常的文檔,Doxygen的手冊(manual)即是這麼產生的。
1.3 功能框圖
功能框圖,描述了Doxygen的信息流,見下圖。
2 如何使用
2.1 首次使用
Doxygen具有 圖形化 和 命令行 兩種操作模式。對於初學者,前者非常容易上手。
Ø 打開 bin/ doxywizard.exe,在嚮導中設置各項參數。主要是設置 Wizard->Project頁面下的內容,其他頁面可以保持默認值。這一標籤頁主要是設置欲讀取源碼的地址以及輸出文檔的地址。特別注意的是:必須勾上 “Scan recursively”選項;
Ø 在 doxywizard.exe 裏,打開 Run 標籤頁,選擇工作目錄後,點擊 Run doxygen 按鈕,則自動在上面設置的目標目錄下產生各種輸出:html、Latex等;
2.1.1 中文亂碼的解決方法
這邊有個要特別注意的地方------字符集的問題:假如你欲讀取的文檔中的中文註釋中採用的是GB2312(如 Source insight、記事本等編輯工具,默認的中文字符集即爲GB2312),那麼生成的文檔中中文將是亂碼。這是因爲 Doxygen 默認 輸入字符集 爲UTF-8。我們只需將 Expert->Input->INPUT_ENCODING 修改爲GB2312 即可解決該問題。
2.2 命令行方式
本節介紹 命令行操作的三個步驟。
2.2.1 新建配置文件
有兩種方法。
第一種:通過如下命令產生默認配置文件,而後根據需要編輯 配置文件。
doxygen -g
第二種:通過上節說到的 doxywizard.exe 工具配置,而後保存配置文件。
配置文件的說明,參考 Doxygen 手冊的 Configuration 一節。
2.2.2 運行doxygen
運行如下命令以生成文檔。
doxygen -g
2.2.3 文檔化代碼
本節和上一節介紹了 doxygen 的GUI 和 Command 兩種操作方式。大家根據上面的介紹生成的文檔往往覺得沒有人家 Doxygen 的手冊好看。這就是缺少 文檔化 的緣故。什麼叫“文檔化“,其實就是討論怎麼把你的註釋恰當地放在代碼中,以產生美觀的文檔。文檔化也就是告訴我們:你要用好 Doxygen 的話,應該怎麼寫源碼的註釋。
顯而易見,雖然這一節放在第三個步驟,但在一個新的項目中,這顯然應該是第一個步驟。
3 入門文章
寫到這邊,突然在網上查到了 參考文獻[2-4] 這幾篇文章。覺得沒必要再寫了,人家已經寫得相當好了。
就入門而言,先讀參考文獻[4],再讀參考文獻[3]。
4 配置文件
參考 doxygen manual 和 參考文獻[2]。
5 如何文檔化源碼
參考 doxygen manual 和 參考文獻[2]。
6 進階
參考 doxygen manual 和 參考文獻[5]。
參考文獻[5] 提供了一種在Vim中自動輸入Doxygen 註釋的方式。
7 參考文獻
1. doxygen_manual-1.6.2.chm:位於Doxygen的根目錄
2. 學習用 doxygen 生成源碼文檔 主要學習該文對配置參數的討論
3. Doxygen介紹 裏面的幾個註釋示例比較好
4. 快速上手 快速上手 Doxygen
5. doxygen+VIM文檔實用指南 vim 中增加一些寫 doxygen註釋 的宏
8 聯繫方式
希望這份文檔對您有所幫助,若您發現任何問題或有任何更好的建議,歡迎與我聯繫!
溫陵布衣:
MSN: [email protected]
Mail: sikinzen @yahoo.com.cn
QQ: 526679213