Doxgen+Graphiz+htmlhelp配置

標籤：doxgen   graphiz   htmlhelp   chm   文檔產生器   

查看一些開原始碼經常被一些函數的調用關係給繞進去。找個工具產生個呼叫歷程圖或簡單的文檔對於協助閱讀程式有很大的協助。

 

1 doxgen+graphviz+htmlhelp簡介1.1 doxgen+graphviz+htmlhelp簡介

doxygen產生漂亮的呼叫歷程圖，那就必須安裝形產生工具graphviz軟體，要通過html產生chm文檔，那就要用htmlhelp軟體了，doxygen產生html文檔或其他格式的文檔軟體。 

首先下載三個軟體，均下載windows下的安裝包，

doxygen、Graphviz 、htmlhelp地址如下：

http://download.csdn.net/detail/fasfewatgerjhytsjy/8149961

1.2 目前Doxgen可處理的語言

目前Doxygen可處理的程式語言套件含：

C/C++

Java

IDL (Corba, Microsoft及KDE-DCOP類型)   

而可產生出來的文檔格式有：

HTML

XML

LaTeX

RTF

Unix Man Page

而其中還可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透過一些工具產生出PS或是PDF文檔。

 

2 關於文檔注釋的要求2.1 文檔注釋的類型

並非所有的批註都會被Doxgen所處理，必須依照正確的格式撰寫批註。

原則上，Doxgen僅處理與程式結構相關的批註，如Function，Class，檔案的批註等。

對於Function內部的批註則不做處理。Doxgen可處理下面幾種類型的批註。

（1）JavaDoc類型：

/**
 * ... 批註 ...
 */

（2）Qt類型：

/*!
 * ... 批註 ...
 */

（3）單行型式的批註：

/// ... 批註 ...

或    

//! ... 批註 ...

我的推薦：多行用JavaDoc，單行用/// ... 批註 ...

2.2 文檔注釋的位置

Doxgen對於批註視為在解釋後面的程式碼。也就是說，任何一個批註都是在說明其後的程式碼。

對於批註前面的程式碼，Doxgen只能識別class的member或者Function的參數上。需要下面格式的批註符號。

/*!< ... 批註 ... */
/**< ... 批註 ... */
//!< ... 批註 ...
///< ... 批註 ...

2.3 注釋指令和格式

使用Doxgen產生說明文檔時候，Doxgen會協助您parsing您的程式碼。並且依據程式結構建立對應的檔案。然後將您的批註依據其位置套入正確的地方。除了文字以外，還有一些其它特別的指定，如@param，@return等。通過這些指令可以告訴Doxgen後面的批註是在說明什麼東西。Doxgen通過指定，能協助我們做些特別的處理或者排版，甚至是製作參考連結。

（1）常用指令

@file	檔案的批註說明。
@author	作者的資訊
@brief	用於class 或function的批註中，後面為class 或function的簡易說明。
@param	格式為 @param arg_name 參數說明 主要用於函式說明中，後面接參數的名字，然後再接關於該參數的說明。
@return	後面接函數傳回值的說明。用於function的批註中。說明該函數的傳回值。
@retval	格式為 @retval value 傳回值說明 主要用於函式說明中，說明特定傳回值的意義。所以後面要先接一個傳回值。然後在放該傳回值的說明。

Doxygen 所支援的指令很多，有些甚至是關於輸出排版的控制。您可從Doxygen的使用說明中找到詳盡的說明。

（2）我們先說明在Doxygen 中對於類別或是函數批註的一個特定格
式。
    /**
     * class或function的簡易說明...
     *
     * class或function的詳細說明...
     * ...
     */

在Doxygen 處理一個class 或是function注
解時，會先判斷第一行為簡易說明。這個簡易說明將一直到空一行的
出現。或是遇到第一個"." 為止。之後的批註將會被視為詳細說明。
兩者的差異在於Doxygen 在某些地方只會顯示簡易說明，而不顯示詳
細說明。如：class 或function的列表。
另一種比較清楚的方式是：

指定@brief的指令。這將會明確的告訴
Doxygen，何者是簡易說明。例如：

    /**
     * @brief class或function的簡易說明...
     *
     * class或function的詳細說明...
     * ...
     */
（3）除了這個class及Function外，Doxgen也可針對檔案做說明，條件是該批註需要置於檔案的前面。主要也是利用一些指令，通常這部分註解都會放在檔案的開始地方。如：

/*! @file myfile.h
        @brief 檔案簡易說明
    
        詳細說明.
        
        @author 作者資訊
    */

（4）舉例

下面我們準備一組example.h 及example.cpp 來說明Doxygen 批註的使用方式：
example.h:
    /**
     * @file 本範例的include檔案。
     *
     * 這個檔案只定義example這個class。
     *
     * @author [email protected]
     */   
    #define EXAMPLE_OK  0   ///< 定義EXAMPLE_OK的宏為0。
    
    /**
     * @brief Example class的簡易說明
     *
     * 本範例說明Example class。
     * 這是一個極為簡單的範例。
     * 
     */
    class Example {
        private:
            int var1 ; ///< 這是一個private的變數
        public:
            int var2 ; ///< 這是一個public的變數成員。
            int var3 ; ///< 這是另一個public的變數成員。
            void ExFunc1(void); 
            int ExFunc2(int a, char b);
            char *ExFunc3(char *c) ;
    };
    
    
example.cpp:
    /**
     * @file 本範例的程式碼檔案。
     *
     * 這個檔案用來定義example這個class的
     * member function。
     *
     * @author [email protected]
     */

    /**
     * @brief ExFunc1的簡易說明
     *
     * ExFunc1沒有任何參數及傳回值。
     */
    void Example::ExFunc1(void)
    {
        // empty funcion.
    }

    /**
     * @brief ExFunc2的簡易說明
     *
     * ExFunc3()傳回兩個參數相加的值。
     *
     * @param a 用來相加的參數。
     * @param b 用來相加的參數。
     * @return 傳回兩個參數相加的結果。
     */
    int ExFunc2(int a, char b)
    {
        return (a+b);
    }
    
    /**
     * @brief ExFunc3的簡易說明
     *
     * ExFunc3()只傳回參數輸入的指標。
     *
     * @param c 傳進的字元指標。
     * @retval NULL Null 字元串。
     * @retval !NULL 非Null 字元串。
     */
    char * ExFunc2(char * c)
    {
        return c;
    }  

3 配置步驟

下面就講解下如何使用了

運行doxygen的步驟和基本介面如，

（1）Destination Directory可以用相對路徑，如：運行路徑是C:/Users/263/Desktop,那麼上面的路徑直接填寫doc/doc

（2）Graphviz產生函數調用圖源檔案和工作目錄必須是英文。

這種選擇，在html中沒有搜尋。搜尋功能在CHM中區產生。

要產生HTML有搜尋功能的文檔，需要再html選項中選擇plain html。

說明：編碼格式，UTF-8 是首選。如果需要顯示中文則選擇GB2312.

TAB_SIZE 主要是協助檔案中代碼的縮排尺寸，譬如@code和@endcode段中代碼的排版，建議設定成4。

OPTIMIZE_OUTPUT_FOR_C 這個選項選擇後，產生文檔的一些描述性名稱會發生變化，主要是符合C習慣。如果

是純C代碼，建議選擇。

SUBGROUPING這個選項選擇後，輸出將會按類型分組。

Build頁面，這個頁面是產生協助資訊中比較關鍵的配置頁面：

EXTRACT_ALL 表示：輸出所有的函數，但是private和static函數不屬於其管制。

EXTRACT_PRIVATE 表示：輸出private函數。

EXTRACT_STATIC 表示：輸出static函數。同時還有幾個EXTRACT，相應查看文檔即可。

HIDE_UNDOC_MEMBERS 表示：那些沒有使用doxygen格式描述的文檔（函數或類等）就不顯示了。當然，如果EXTRACT_ALL被啟用，那麼這個標誌其實是被忽略的。

INTERNAL_DOCS 主要指：是否輸出註解中的@internal部分。如果沒有被啟動，那麼註解中所有的@internal部分都

將在目標協助中不可見。

CASE_SENSE_NAMES 表示：是否關注大小寫名稱，注意，如果開啟了，那麼所有的名稱都將被小寫。對於C/C++這種

字母相關的語言來說，建議永遠不要開啟。

HIDE_SCOPE_NAMES 表示：域隱藏，建議永遠不要開啟。

SHOW_INCLUDE_FILES 表示：是否顯示包含檔案，如果開啟，協助中會專門產生一個頁面，裡麵包含所有包含檔案的列

表。

INLINE_INFO ：如果開啟，那麼在協助文檔中，inline函數前面會有一個inline修飾詞來標明。

SORT_MEMBER_DOCS ：如果開啟，那麼在協助文檔列表顯示的時候，函數名稱會排序，否則按照解釋的順序顯

示。

GENERATE_TODOLIST ：是否產生TODOLIST頁面，如果開啟，那麼包含在@todo註解中的內容將會單獨產生並顯

示在一個頁面中，其他的GENERATE選項同。

SHOW_USED_FILES ：是否在函數或類等的協助中，最下面顯示函數或類的來源檔案。

SHOW_FILES ：是否顯示檔案清單頁面，如果開啟，那麼協助中會存在一個一個檔案清單索引頁面。

說明：1，CHM_FILE檔案名稱需要加上尾碼（xx.chm）。

2，如果在 Wizard 的 Output Topics 中選擇了 prepare for compressed HTML (.chm)選項，此處就會要求選擇 hhc.exe 程式的位置。在 windows help workshop 安裝目錄下可以找到 hhc.exe，如：C:\Program Files\HTML Help Workshop。

3，為瞭解決DoxyGen產生的CHM檔案的左邊樹目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312即可。

4，GENERATE_CHI 表示索引檔案是否單獨輸出，建議關閉。否則每次產生兩個檔案，比較麻煩。

5，TOC_EXPAND 表示是否在索引中列舉成員名稱以及分組（譬如函數，枚舉）名稱。

 參考

http://blog.csdn.net/fly542/article/details/7164633

Doxgen+Graphiz+htmlhelp配置