Doxygen的使用,配置及例項
Doxygen是一種開源跨平臺的,以類似JavaDoc風格描述的文件系統,可以從一套歸檔原始檔開始,生成文件
下載Doxygen + Graphviz
Doxygen可以生成動態文件
Graphviz可以生成檢視連線將.c檔案中所用到的函式、標頭檔案生成一個樹狀結構並且設定之後可以生成相對應的函式的跳轉,方便查詢函式。
一、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
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 空字串。 |
@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>全域性和靜態變數註釋
例如:
1 2 3 |
|
使用文件詳見: Doxygen使用