windows下vim和Doxygen自動生成代碼文檔

1. 下載DoxygenToolkit 下載地址：http://www.vim.org/scripts/script.php?script_id=987

2. 把DoxygenToolkit.vim放入../Vim/vim72/plugin

3. 修改_vimrc的配置,我的配置是

let g:DoxygenToolkit_paramTag_pre="@param "

let g:DoxygenToolkit_returnTag="@returns "

let g:DoxygenToolkit_blockHeader="--------------------------------------------------------------------------"

let g:DoxygenToolkit_blockFooter="----------------------------------------------------------------------------"

let g:DoxygenToolkit_authorName="Leon Lee"

4. 使用命令

DoxAuthor:將文件名，作者，時間等關鍵字自動填好

DoxLic:license註釋

Dox：函數及類註釋

5、使用Doxygen的一般步驟

a) 下載 Doxygen軟件(本人Cygwin自帶該軟件)

b) 下載 Graphviz

c) 安裝 Doxygen 和 Graphviz（可選）

d) 準備一個配置文件（Doxyfile）

e) 按照Doxygen規則給源代碼添加註釋，將代碼文檔化

f) 運行Doxygen 產生和源代碼對應的文檔。

6. 生成Doxyfile方法

運行doxygen -g
編輯配置文件

以下文字摘錄於http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/index.html

配置文件採用 <TAGNAME> = <VALUE> 這樣的結構，與 Make 文件格式相似。下面是最重要的標記：

<OUTPUT_DIRECTORY>：必須在這裏提供一個目錄名，例如 /home/user1/documentation，這個目錄是放置生成的文檔文件的位置。如果提供一個不存在的目錄名，doxygen 會以這個名稱創建具有適當用戶權限的目錄。
<INPUT>：這個標記創建一個以空格分隔的所有目錄的列表，這個列表包含需要生成文檔的 C/C++ 源代碼文件和頭文件。例如，請考慮以下代碼片段：
INPUT = /home/user1/project/kernel /home/user1/project/memory
在這裏，doxygen 會從這兩個目錄讀取 C/C++ 源代碼。如果項目只有一個源代碼根目錄，其中有多個子目錄，那麼只需指定根目錄並把 <RECURSIVE> 標記設置爲 Yes。
<FILE_PATTERNS>：在默認情況下，doxygen 會搜索具有典型 C/C++ 擴展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果 <FILE_PATTERNS> 標記沒有相關聯的值，doxygen 就會這樣做。如果源代碼文件採用不同的命名約定，就應該相應地更新這個標記。例如，如果項目使用 .c86 作爲 C 文件擴展名，就應該在 <FILE_PATTERNS> 標記中添加這個擴展名。
<RECURSIVE>：如果源代碼層次結構是嵌套的，而且需要爲所有層次上的 C/C++ 文件生成文檔，就把這個標記設置爲 Yes。例如，請考慮源代碼根目錄層次結構 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目錄。如果這個標記設置爲 Yes，doxygen 就會遞歸地搜索整個層次結構並提取信息。
<EXTRACT_ALL>：這個標記告訴 doxygen，即使各個類或函數沒有文檔，也要提取信息。必須把這個標記設置爲 Yes。
<EXTRACT_PRIVATE>：把這個標記設置爲 Yes。否則，文檔不包含類的私有數據成員。
<EXTRACT_STATIC>：把這個標記設置爲 Yes。否則，文檔不包含文件的靜態成員（函數和變量）。

清單 3 給出一個 Doxyfile 示例。

清單 3. 包含用戶提供的標記值的 doxyfile 示例

                
OUTPUT_DIRECTORY = /home/user1/docs
EXTRACT_ALL = yes
EXTRACT_PRIVATE = yes
EXTRACT_STATIC = yes
INPUT = /home/user1/project/kernel
#Do not add anything here unless you need to. Doxygen already covers all 
#common formats like .c/.cc/.cxx/.c++/.cpp/.inl/.h/.hpp
FILE_PATTERNS = 
RECURSIVE = yes

運行 doxygen

在 shell 提示下輸入 doxygen Doxyfile（或者已爲配置文件選擇的其他文件名）運行 doxygen。在最終生成 Hypertext Markup Language（HTML）和 Latex 格式（默認）的文檔之前，doxygen 會顯示幾個消息。在生成文檔期間，在 <OUTPUT_DIRECTORY> 標記指定的文件夾中，會創建兩個子文件夾 html 和 latex。清單 4 是一個 doxygen 運行日誌示例。

清單 4. doxygen 的日誌輸出

                
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for files to exclude
Reading input files...
Reading and parsing tag files
Preprocessing /home/user1/project/kernel/kernel.h
…
Read 12489207 bytes
Parsing input...
Parsing file /project/user1/project/kernel/epico.cxx
…
Freeing input...
Building group list...
..
Generating docs for compound MemoryManager::ProcessSpec
…
Generating docs for namespace std
Generating group index...
Generating example index...
Generating file member index...
Generating namespace member index...
Generating page index...
Generating graph info page...
Generating search index...
Generating style sheet...

文檔輸出格式

除了 HTML 之外，doxygen 還可以生成幾種輸出格式的文檔。可以讓 doxygen 生成以下格式的文檔：

UNIX 手冊頁：把 <GENERATE_MAN> 標記設置爲 Yes。在默認情況下，會在 <OUTPUT_DIRECTORY> 指定的目錄中創建 man 子文件夾，生成的文檔放在這個文件夾中。必須把這個文件夾添加到 MANPATH 環境變量中。
Rich Text Format（RTF）：把 <GENERATE_RTF> 標記設置爲 Yes。把 <RTF_OUTPUT> 標記設置爲希望放置 .rtf 文件的目錄；在默認情況下，文檔放在 OUTPUT_DIRECTORY 中的 rtf 子文件夾中。要想支持跨文檔瀏覽，應該把 <RTF_HYPERLINKS> 標記設置爲 Yes。如果設置這個標記，生成的 .rtf 文件會包含跨文檔鏈接。
Latex：在默認情況下，doxygen 生成 Latex 和 HTML 格式的文檔。在默認的 Doxyfile 中，<GENERATE_LATEX> 標記設置爲 Yes。另外，<LATEX_OUTPUT> 標記設置爲 Latex，這意味着會在 OUTPUT_DIRECTORY 中創建 latex 子文件夾並在其中生成 Latex 文件。
Microsoft® Compiled HTML Help（CHM）格式：把 <GENERATE_HTMLHELP> 標記設置爲 Yes。因爲在 UNIX 平臺上不支持這種格式，doxygen 只在保存 HTML 文件的文件夾中生成一個 index.hhp 文件。您必須通過 HTML 幫助編譯器把這個文件轉換爲 .chm 文件。
Extensible Markup Language（XML）格式：把 <GENERATE_XML> 標記設置爲 Yes。（注意，doxygen 開發團隊還在開發 XML 輸出）。

清單 5 提供的 Doxyfile 示例讓 doxygen 生成所有格式的文檔。

清單 5. 生成多種格式的文檔的 Doxyfile

                
#for HTML 
GENERATE_HTML = YES
HTML_FILE_EXTENSION = .htm

#for CHM files
GENERATE_HTMLHELP = YES

#for Latex output
GENERATE_LATEX = YES
LATEX_OUTPUT = latex

#for RTF
GENERATE_RTF = YES
RTF_OUTPUT = rtf 
RTF_HYPERLINKS = YES

#for MAN pages
GENERATE_MAN = YES
MAN_OUTPUT = man
#for XML
GENERATE_XML = YES

=====================================分割線=============================

以下是另一篇相關使用方法的轉載:

在Linux下面開發，在代碼中一般註釋doxygen格式的註釋，這是幫助我們生成文檔的一個好方法。

對於doxygen的主要是語法，網上有很多的說明，有個工程：GNOME Power Manager裏面的doxygen

註釋寫的非常好，你們可以下載下來看看，並且可以借鑑到自己的實際開發中。

這裏我想說的是：如何從source code 總提取開源軟件的文檔。

有3個工具可以先安裝一下：

1 doxygen

2 Graphviz

3 htmlhelp

1 doxygen是大名鼎鼎代碼文檔工具。

下載地址：www.doxygen.org