Doxygen 是一種用於 C/C++、Java™、Python 和其他編程語言的文檔系統, 其功能類似於 java.
1. 安裝doxygen
安裝doxygen前最好先安裝graphviz軟件包, 不然可能會安裝不成功:
sudo apt-get graphviz參考官方的安裝教程. 這一步還是非常容易的, 如果沒有root權限, 可以使用 --prfix 參數指定安裝目錄:
./configure --prefix=/home/user1/bin2. 使用doxygen生成文檔
用doxygen命令來生成文檔需要指定一個配置文件, 初次使用時可以執行 doxygen -g 命令, 執行完成後會在當前目錄下生成一個默認的配置文件模板 Doxyfile , 該文件中包含了豐富的有關配置參數的註釋, 高級用戶可以好好研究下. 也可用doxygen -g filename 指定配置文件名. 然後執行 doxygen Doxyfile 命令開始就可以開始生成代碼文檔了, 文檔保存在當前目錄的html/目錄中, 非常簡單吧.
doxygen不僅可以生成html文件, 也可以生成pdf, man pages, rtf, latex, xml, chm等多種格式的文檔, 默認生成html和latex, 只需要在配置文件中設置相應的 <GENERATE_MAN>, <GENERATE_RTF>,<GENERATE_HTMLHELP>, <GENERATE_XML> 等相應的標籤爲
YES 即可.
3. 編輯配置文件 Doxyfile
配置文件採用 TAG = value [value, ...] 這樣的結構，與 Make 文件格式相似。可以仔細看看默認生成的Doxyfile文件, 裏面每個標記都有註釋, 下面是最重要的標記：
- <OUTPUT_DIRECTORY>：必須在這裏提供一個目錄名，例如 /home/user1/documentation，這個目錄是放置生成的文檔文件的位置。如果提供一個不存在的目錄名，doxygen 會以這個名稱創建具有適當用戶權限的目錄。
- <INPUT>：這個標記創建一個以空格分隔的所有目錄的列表，這個列表包含需要生成文檔的 C/C++ 源代碼文件和頭文件。例如，請考慮以下代碼片段：
INPUT = /home/user1/project/kernel /home/user1/project/memory- <EXCLUDE>:
從文檔目錄排除相應的目錄
- <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。否則，文檔不包含文件的靜態成員（函數和變量）。
4. doxygen 中的特殊標記
Doxyfile 中的 <ENABLE_PREPROCESSING> 標記在默認情況下設置爲 Yes。爲了執行宏展開，還應該把 <MACRO_EXPANSION> 標記設置爲 Yes。
在文檔中，可能希望只展開特定的宏。爲此，除了把 <ENABLE_PREPROCESSING> 和 <MACRO_EXPANSION> 標記設置爲 Yes之外，還必須把
<EXPAND_ONLY_PREDEF> 標記設置爲 Yes（這個標記在默認情況下設置爲 No），並在<PREDEFINED> 或 <EXPAND_AS_DEFINED>
標記中提供宏的細節。如:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = CONTAINER只展開宏 CONTAINER .
5. 生成圖形和圖表
在默認情況下，Doxyfile 把 <CLASS_DIAGRAMS> 標記設置爲 Yes。這個標記用來生成類層次結構圖。要想生成更好的視圖，可以從Graphviz 下載站點 下載 dot 工具。Doxyfile 中的以下標記用來生成圖表：
<CLASS_DIAGRAMS>：在 Doxyfile 中這個標記默認設置爲 Yes。如果這個標記設置爲 No，就不生成繼承層次結構圖。
<HAVE_DOT>：如果這個標記設置爲 Yes，doxygen 就使用 dot 工具生成更強大的圖形，比如幫助理解類成員及其數據結構的協作圖。注意，如果這個標記設置爲 Yes，<CLASS_DIAGRAMS> 標記就無效了。
<CLASS_GRAPH>：如果 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，就使用 dot 生成繼承層次結構圖，而且其外觀比只使用 <CLASS_DIAGRAMS> 時更豐富。
<COLLABORATION_GRAPH>：如果 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，doxygen 會生成協作圖（還有繼承圖），顯示各個類成員（即包含）及其繼承層次結構。
<CLASS_DIAGRAMS>：在 Doxyfile 中這個標記默認設置爲 Yes。如果這個標記設置爲 No，就不生成繼承層次結構圖。
<HAVE_DOT>：如果這個標記設置爲 Yes，doxygen 就使用 dot 工具生成更強大的圖形，比如幫助理解類成員及其數據結構的協作圖。注意，如果這個標記設置爲 Yes，<CLASS_DIAGRAMS> 標記就無效了。
<CLASS_GRAPH>：如果 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，就使用 dot 生成繼承層次結構圖，而且其外觀比只使用 <CLASS_DIAGRAMS> 時更豐富。
<COLLABORATION_GRAPH>：如果 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，doxygen 會生成協作圖（還有繼承圖），顯示各個類成員（即包含）及其繼承層次結構。
6. 代碼文檔樣式
如果使用C/C++, 最簡單的註釋風格就是
/**
* text...
*
*/也可以加一些標記, '@' 和 '/' 等價:
/**
* @brief bababa
*
* detailed info....
*
*/Doxygen 允許一條簡短註釋,加上一條詳細註釋.其格式也是多樣的. 一般,在 JAVADOC_AUTOBRIEF = NO時,簡短註釋(///@brief )後空一行,然後再是詳細註釋. 當 JAVADOC_AUTOBRIEF = YES時,並且簡短註釋以第一個句號結束,句號後跟一空格(即'. ');或者是新起一行,就可以寫詳細註釋了.
如果同一代碼條目在聲明和定義處都有簡短註釋和詳細註釋, 則文檔只採用聲明前的簡短註釋和定義前的詳細註釋.
如果是在行尾註釋變量,參數等,在你選用的註釋格式後面加上'<', 如: ///<行尾的註釋.
下面有一個註釋的例子:
----------------------------- Example Begin ---------------------------------
///@file socket_c.h head file of class socket_c.
///Define the interface of class socket_c.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $ 這是普通註釋, 不會生成在文檔中
///@brief class of server socket.
class socket_c
{
private:
public:
///@brief handle the connections of clients.
///@param server the server ip address.
///@param serv_port the server #port.
///@return connected socketfd.
# 具體返回值的註釋,格式: ///@retval 返回值 該返回值的註釋.
///@retval connfd on success.
///@retval 0 on EINTR - system call.
///@retval -1 on error.
# 參見...,格式: ///@see 參見的類/文件等.
///@see main_ppc.cpp
int accept_client(const int listenfd);
};
///@brief structure of child process.
struct child_proc_s
{
# 行尾的註釋,格式: ///< 註釋內容.
pid_t child_pid; ///<child process id.
int child_pipefd; ///<parent's stream pipe to/from child.
};
# 全局變量的註釋,也可以採用上面的行尾格式進行註釋.
///gloable variable for signal.
pid_t g_pid = 0;
----------------------------- Example End ---------------------------------7. 在vim中使用Doxygen插件: DoxygenToolkit
該插件可以自動生成Doxygen註釋, 非常方便. 安裝好之後, 需要在VIM的配置文件中(/etc/vimrc)爲doxygentoolkit這個插件配置一些全局變量：
let g:doxygenToolkit_authorName="your name"
let g:doxygenToolkit_briefTag_funcName="yes"參考:
