|
日期 |
修訂版本 |
描述 |
作者 |
|
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