Doxygen的使用，配置及實例

 

Doxygen是一種開源跨平臺的，以相似JavaDoc風格描述的文檔系統，能夠從一套歸檔源文件開始，生成文檔

下載Doxygen + Graphviz

Doxygen能夠生成動態文檔

Graphviz能夠生成視圖鏈接將.c文件中所用到的函數、頭文件生成一個樹狀結構而且設置以後能夠生成相對應的函數的跳轉，方便查詢函數。  

1、Doxygen的使用步驟

1.1Doxygen配置方法

1.1.1>Doxygen的主頁面

首先修改Project name，選擇掃描源代碼的目錄，Source code directory：勾選Scan recursively：

 

 

1.2>在Wizard的Topics下的Mode，選擇All Entities，能夠輸出相對完整的功能，是否包含源代碼看自身狀況，在下面選擇好本身的語言。這裏得是C因此選擇C or PHP

 

 

 

1.3>在Output中，若是你須要輸出chm格式，勾選chm,沒有要求的話html就能夠了

 

1.4>在Diagrams中選擇使用GraphViz包，來輸出UML，GraphViz包能夠幫助創建一些樹狀視圖。

 

1.5>Expert中，你須要首選肯定你所輸出的語言，我的使用中文在Expert的Input中，很重要的是INPUT_ENCODING項，若是使用的爲微軟默認字符集請填寫GBK，否則目錄亂碼,當前選擇UTF-8，輸出語言選擇的是Chinese.

1.6>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.7>Expert>Input頁按照下圖進行設置調整參數。

 

1.8>

1.若是在 Wizard 的 Output Topics 中選擇了 prepare for compressed HTML (.chm)選項，此處就會要求選擇 hhc.exe 程序的位置。在 windows help workshop 安裝目錄下能夠找到 hhc.exe。

2.爲了解決Doxygen生成的CHM文件的左邊樹目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312便可。

3.GENERATE_CHI 表示索引文件是否單獨輸出，建議關閉。不然每次生成兩個文件，比較麻煩。

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

 

 

1.8>運行doxygen

 

1.9>運行結束

 

 

二.註釋規範

2.1> Doxygen註釋種類

Doxygen註釋的種類有多種

1.

/**

 * ....描述...

*/

 

2.

/*!

 * ....描述...

*/

或者

/*!

  ....描述...

*/

注：註釋塊中的星號(*)是可選的，可寫可不寫。

3

///

///....描述...

///

或者

//!

//!....描述...

//!

4

////////////////////////

///....描述...

//////////////////////////

2.2>Doxygen支持的指令

能夠在註釋中加一些Doxygen支持的指令，主要做用是控制輸出文檔的排版格式，使用這些指令時須要在前面加上「\」或者「@」（JavaDoc風格）符號，告訴Doxygen這些是一些特殊的指令，經過加入這些指令以及配備相應的文字，能夠生成更加豐富的文檔，下面對比較經常使用的指令作一下簡單介紹。

@file	檔案的批註說明。
@author	做者的信息
@brief	用於class或function的簡易說明 eg：@brief本函數負責打印錯誤信息串
@param	主要用於函數說明中，後面接參數的名字，而後再接關於該參數的說明
@return	描述該函數的返回值狀況 eg: @return 本函數返回執行結果，若成功則返回TRUE，不然返回FLASE
@retval	描述返回值類型 eg:@retval NULL 空字符串。 @retval !NULL 非空字符串。
@note	註解
@attention	注意
@warning	警告信息
@enum	引用了某個枚舉，Doxygen會在該枚舉處產生一個連接 eg：@enum CTest::MyEnum
@var	引用了某個變量，Doxygen會在該枚舉處產生一個連接 eg：@var CTest::m_FileKey
@class	引用某個類， 格式：@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h"
@exception	可能產生的異常描述 eg:@exception 本函數執行可能會產生超出範圍的異常

 

2.3>文件註釋

放於文件的開頭，例如：

/**

* @file       filename

* @brief      This is a brief description.

* @details This is the detail description.

* @author     author

* @date       date

* @version A001

* @par Copyright (c):

*      XXX公司

* @par History:        

*   version: author, date, desc\n

*/

2.3>函數註釋

放於函數聲明前，例如：

/** 下面是一個含有兩個參數的函數的註釋說明（簡述） 

 * 

 *     這裏寫該函數的詳述信息 

 *     @param a 被測試的變量（param描述參數） 

 *     @param s 指向描述測試信息的字符串 

 *     @return    測試結果 （return描述返回值） 

 *     @see    Test()    （本函數參考其它的相關的函數，這裏做一個連接） 

 *     @note    (note描述須要注意的問題) 

 */
int testMe(int a,const char *s);

2.4>數據結構註釋

應放於函數聲明前，例如：

/**

 * The brief description.

 * The detail description.

 */

typedef struct

{

    int var1;///<Description of the member variable

}XXXX;

或者

typedef struct box {

    成員變量註釋（enum的各個值也如此註釋）：

    double length; ///< The length of the box

    double width; ///< The width of the box

    double height; ///< The height of the box

};

2.5>宏定義註釋

放於宏定義上方或者右側，例如：

/** Description of the macro */

#define XXXX_XXX_XX      ox7fffffff

或者

#define XXXX_XXX_XX      0 ///< Description of the macro.

2.6>全局和靜態變量註釋

例如：

/**  Description of global variable  */
int g_xxx = 0;
static int s_xxx = 0; ///<  Description of static variable

使用文檔詳見：  Doxygen使用