Doxygen詳細介紹

1 序言  

   爲代碼寫註釋一直是大多數程序員有些困擾的事情。當前程序員都能接受爲了程序的可維護性、可讀性編碼的同時寫註釋的說法，但對哪些地方應該寫註釋，註釋如何寫，寫多少等這些問題，不少程序員仍然沒有答案。更頭痛的是寫文檔，以及維護文檔的問題，開發人員一般能夠忍受編寫或者改動代碼時編寫或者修改對應的註釋，但以後須要修正相應的文檔卻比較困難。若是能從註釋直接轉化成文檔，對開發人員無疑是一種福音。而doxygen就能把遵照某種格式的註釋自動轉化爲對應的文檔。

    Doxygen是基於GPL的開源項目，是一個很是優秀的文檔系統，當前支持在大多數unix（包括Linux），windows家族，Mac系統上運行，徹底支持C++, C, Java, IDL（Corba和Microsoft 家族）語言，部分支持PHP和C#語言，輸出格式包括HTML、latex、RTF、ps、PDF、壓縮的HTML和unix manpage。有不少開源項目（如log4cpp和CppUnit）都使用了doxygen文檔系統。

    Doxygen 就是這樣的一個工具。在您寫批註時，稍微按照一些它所制訂的規則。接着，他就能夠幫您產生出漂亮的文檔了。所以，Doxygen 的使用可分爲兩大部分。首先是特定格式的批註撰寫，第二即是利用Doxygen的工具來產生文件。

2  Doxygen及相關工具的下載

（1）Doxygen的最新版本，能夠從Doxygen的網站下載。 

（2）Graphviz是一個圖形可視化軟件。Doxygen使用Graphviz生成各類圖形，例如類的繼承關係圖、合做圖，頭文件包含關係圖等。能夠從Graphviz的網站下載Graphviz的最新版本。

 

4     Doxygen配置文件

4.1   生成Doxygen配置文件

 

運行Doxywizard建立配置文件。
能夠直接點「Save...」按鈕，將保存默認的配置文件，名爲Doxyfile，內容是Doxygen的默認設置。Doxyfile是普通文本文件，咱們能夠直接打開手動編輯。不過在Doxywizard的界面上填寫也很方便，每一個參數都有詳細提示。建議用Doxywizard完成第一次設置。之後若是須要調整個別參數，能夠直接編輯Doxyfile。

上述Doxywizard界面中提供了生成Doxygen文檔的4個步驟，按照上述步驟一步步執行就能夠生成漂亮的文檔了。

第一步是生成配置文件，提供三種方式，Wizard方式指簡約方式，在其中只提供一些重要的參數設置，其他的均爲默認值；Expert方式爲詳細設置方式，經過該選項能夠詳細地配置Doxygen的各個配置項；最後一種是Load方式，用於導入之前生成的Doxygen配置文件，導入後能夠再點擊Expert進行修改。

4.2    配置選項含義詳解

在上述界面中點擊Expert按鈕，或者用文本方式打開Doxyfile文件，能夠看到Doxygen的參數配置項特別多，各個參數的含義其實也並不難掌握，在Doxygen的幫助手冊中有詳細的介紹，下面我介紹一些經常使用的參數含義，其他的參數大多能夠設置爲默認值。

DOXYFILE_ENCODING	Doxygen文件的編碼方式，默認爲UTF-8，若但願支持中文，最好設置爲 GB2312
PROJECT_NAME	Project 的名字，以一個單詞爲主，多個單詞請使用雙引號括住。
PROJECT_VERSION	Project的版本號碼。
OUTPUT_DIRECTORY	輸出路徑。產生的文件會放在這個路徑之下。若是沒有填這個路徑，將會以目前所在路徑做爲輸出路徑。
OUTPUT_LANGUAGE	輸出語言, 默認爲English 。
EXTRACT_ALL	爲NO，只解釋有doxygen格式註釋的代碼；爲YES，解析全部代碼，即便沒有註釋
EXTRACT_PRIVATE	是否解析類的私有成員
EXTRACT_STATIC	是否解析靜態項
EXTRACT_LOCAL_CLASSES	是否解析源文件（cpp文件）中定義的類
INPUT	指定加載或找尋要處理的程序代碼文件路徑。這邊是一個表列式的型態。而且可指定檔案及路徑。
FILE_PATTERNS	若是您的INPUT Tag 中指定了目錄。您能夠透過這個Tag來要求Doxygen在處理時，只針對特定的檔案進行動做。例如：您但願對目錄下的擴展名爲.c, .cpp及.h的檔案做處理。您可設定FILE_PATTERNS = *.c, *.cpp, *.h。
RECURSIVE	這是一個布爾值的Tag，只接受YES或NO。當設定爲YES時，INPUT所指定目錄的全部子目錄都會被處理.
EXCLUDE	若是您有某幾個特定檔案或是目錄，不但願通過Doxygen處理。您可在這個Tag中指定。
EXCLUDE_PATTERNS	相似於FILE_PATTERNS的用法，只是這個Tag是供EXCLUDE所使用。
SOURCE_BROWSER	若是設定爲YES，則Doxygen會產生出源文件的列表，以供查閱。
INLINE_SOURCES	若是設定爲YES ，則函數和類的實現代碼被包含在文檔中
ALPHABETICAL_INDEX	若是設定爲YES，則一個依照字母排序的列表會加入在產生的文件中。（有不少類、結構等項時建議設爲YES）
GENERATE_HTML	若設定爲YES ，就會產生HTML版本的說明文件。HTML文件是Doxygen預設產生的格式之一。
HTML_OUTPUT	HTML文件的輸出目錄。這是一個相對路徑，因此實際的路徑爲OUTPUT_DIRECTORY加上HTML_OUTPUT。這個設定預設爲html。
GENERATE_HTMLHELP	是否生成壓縮HTML格式文檔（.chm）
HTML_FILE_EXTENSION	HTML文件的擴展名。預設爲.html。
HTML_HEADER	要使用在每一頁HTML文件中的Header。若是沒有指定，Doxygen會使用本身預設的Header。
HTML_FOOTER	要使用在每一頁HTML文件中的Footer。若是沒有指定，Doxygen會使用本身預設的Footer。
HTML_STYLESHEET	您可給定一個CSS 的設定，讓HTML的輸出結果更完美。
GENERATE_HTMLHELP	如設定爲YES，Doxygen會產生一個索引文件。這個索引文件在您須要製做windows 上的HTML格式的HELP檔案時會用的上。
GENERATE_TREEVIEW	若設定爲YES，Doxygen會幫您產生一個樹狀結構，在畫面左側。這個樹狀結構是以JavaScript所寫成。因此須要新版的Browser才能正確顯示。
TREEVIEW_WIDTH	用來設定樹狀結構在畫面上的寬度。
GENERATE_LATEX	設定爲YES 時，會產生LaTeX 的文件。不過您的系統必須要有安裝LaTeX 的相關工具。
LATEX_OUTPUT	LaTeX文件的輸出目錄，與HTML_OUTPUT用法相同，同樣是指在OUTPUT_DIRECTORY之下的路徑。預設爲latex。
LATEX_CMD_NAME	LaTeX程序的命令名稱及檔案所在。預設爲latex。
GENERATE_RTF	若設定爲YES ，則會產生RTF 格式的說明檔。
RTF_OUTPUT	與HTML_OUTPUT 用法相同，用來指定RTF 輸出檔案路徑。預設爲rtf。
GENERATE_MAN	若設定爲YES ，則會產生Unix Man Page 格式的說明文件。
MAN_OUTPUT	與HTML_OUTPUT 用法相同，用來指定Man Page的輸出目錄。預設爲man。
GENERATE_XML	若設定爲YES ，則會產生XML 格式的說明文件。
ENABLE_PREPROCESSING	若設定爲YES ，則Doxygen 會激活C 的前置處理器來處理原始檔。
PREDEFINED	可讓您自行定義一些宏。相似於gcc 中的-D選項。
CLASS_DIAGRAMS	這個標記用來生成類繼承層次結構圖。要想生成更好的視圖，能夠從 Graphviz 下載站點 下載 dot 工具。Doxyfile 中的如下標記用來生成圖表：
HAVE_DOT	若是這個標記設置爲 Yes，doxygen 就使用 dot 工具生成更強大的圖形，好比幫助理解類成員及其數據結構的協做圖。注意，若是這個標記設置爲 Yes，<CLASS_DIAGRAMS> 標記就無效了
CLASS_GRAPH	若是 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，就使用 dot 生成繼承層次結構圖
GRAPHICAL_HIERARCHY	設置爲YES時，將會繪製一個圖形表示的類圖結構

 

 

上面的表格只是描述了一些經常使用的配置，須要更加詳細的信息請參考Doxygen的幫助手冊。

結束語

 

免費學習更多精品課程，登陸樂搏學院官網http://h.learnbo.cn/

或關注咱們的官方微博微信，還有更多驚喜哦~

 

 

 

本文出自 「Jhuster的專欄」 博客