doxygen學習筆記 2012-02-28

Doxygen把本身定義爲「Source code documentation generator tool」（源代碼文檔生成工具）。Doxygen提供一種維護文檔的機制。Doxygen能夠作下面的事情：

一、從已經文檔化的代碼中抽取並生成文檔。生成的文檔格式有html、xml、Tex、rtf、PostScript、帶連接的PDF、chm、Unix man pages等等多種格式，因爲是xml是高度結構化的，因此你能夠經過第三方工具作得更好。

二、從沒有文檔化的代碼中生成代碼結構的文檔。此時可讓讀者快速對代碼樹的結構產生的總體概念，爲進一步閱讀打好基礎。

Doxygen有3個工具的集合，其中doxygen是工具集的核心，此外還存在一個名爲doxytag的工具，用於合併已有的文檔，剩下的一個就是前面的兩個工具的GUI前端doxywizard。

Doxygen安裝方法

一、ubuntu下我使用的是sudo apt-get install doxygen

二、源代碼編譯方式安裝，我沒有試過。網上搜集的命令以下

bash-2.05$ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn

bash-2.05$ cd doxygen-svn

bash-2.05$ ./configure –prefix=/home/user1/bin

bash-2.05$ make

bash-2.05$ make install

Doxygen的使用方法：

一、在項目因此在目錄運行：doxygen -g [config-file]，其中config-file是一個文件名，能夠省略，默認值爲當前目錄的Doxyfile，裏面是UNIX風格的設置──一個變量對應一個值，用等號相連。運行這個命令將會生成一個相應的設置文件，它是默認的。

二、根據須要修改上面的config-file，這是一個普通的文本文件，裏面存在大量註釋，以幫助咱們理解一個設置的含意。做爲簡單的嘗試，你能夠省去這步。這裏可能有一個設置比較重要，就是生成的文檔放在哪裏，默認會生成在當前目錄裏。

三、在項目目錄裏運行命令：doxygen，沒有任何參數，此時會根據上面的設置文件生成知足要求的文檔，若是設置文件裏指定了生成HTML的文檔，那麼生成相應的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。不然，文檔不包含文件的靜態成員（函數和變量）。

生成多種格式的文檔的 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

註釋源代碼

Doxygen支持多種風格的源代碼註釋，也支持自定義風格的註釋

一個例子：

/**

 * @file doxygen.cpp

 * @author abc

 *

 * @brief 這是一個使用Doxygen工具的示例

 * 

 * @details 你們注意到沒有，如上面的\@file等等其實是Doxygen支持的命令 \n

 * 命令是用來幫助Doxygen對相應的信息定位的工具， \n

 * 上面3個命令意義你們一看就明白了。\n

 * Doxygen存在大量命令，官方手冊有命令

 */

/**

 * @brief 一個示例類

 */

class Example

{

public:

        /**

         * @brief 打印內部保存的值

         * @return 自身的引用

         */

        Example& print()

        {

                std::cout << _num << std::endl;

                return *this;

        }

        /**

         * @brief 設置內部的值

         * @param num 須要設置的值

         * @return 自身的引用

         */

        Example& set(int num)

        {

                _num=num;

                return *this;

        }

private:

        int _num;

}

Doxygen命令官方手冊:http://www.stack.nl/~dimitri/doxygen/commands.html