doxygen 生成源碼文檔

使用doxygen 生成源代碼的文檔是至關方便的，本文就簡單整理下doxygen的使用說明

1. 安裝

　關於安裝的問題不作特殊的說明，這裏直接使用命令安裝， 源碼安裝不作介紹

   ubuntu:　

sudo apt-get install doxygen

  centos

sudo yum install doxygen

 

2. 配置文件配置

　關於doxygen主要的部分就在於配置文件的配置， doxygen至關強大，因此配置文件內容有點多。這裏只介紹一部分，你們有興趣能夠繼續深刻研究

　(1) 重要標記

　　配置文件採用 <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。不然，文檔不包含文件的靜態成員（函數和變量）。

   (2) 文檔輸出格式　　

　　除了 HTML 以外，doxygen 還能夠生成幾種輸出格式的文檔。可讓 doxygen 生成如下格式的文檔：

　　UNIX 手冊頁：把 <GENERATE_MAN> 標記設置爲 Yes。在默認狀況下，會在 <OUTPUT_DIRECTORY> 指定的目錄中建立 man 子文件夾，生成的文檔放在這個文件夾中。必須把這個文件夾添加到 MANPATH 環境變量中。

　　Rich Text Format（RTF）：把 <GENERATE_RTF> 標記設置爲 Yes。把 <RTF_OUTPUT> 標記設置爲但願放置 .rtf 文件的目錄；在默認狀況下，文檔放在OUTPUT_DIRECTORY 中的 rtf 子文件夾中。要想支持跨文檔瀏覽，應該把 <RTF_HYPERLINKS> 標記設置爲 Yes。若是設置這個標記，生成的 .rtf文件會包含跨文檔連接。

　　Latex：在默認狀況下，doxygen 生成 Latex 和 HTML 格式的文檔。在默認的 Doxyfile 中，<GENERATE_LATEX> 標記設置爲 Yes。另外，<LATEX_OUTPUT> 標記設置爲 Latex，這意味着會在 OUTPUT_DIRECTORY 中建立 latex 子文件夾並在其中生成 Latex 文件。

　　Microsoft® Compiled HTML Help（CHM）格式：把 <GENERATE_HTMLHELP> 標記設置爲 Yes。由於在 UNIX 平臺上不支持這種格式，doxygen 只在保存HTML 文件的文件夾中生成一個 index.hhp 文件。您必須經過 HTML 幫助編譯器把這個文件轉換爲 .chm 文件。

　　Extensible Markup Language（XML）格式：把 <GENERATE_XML> 標記設置爲 Yes。（注意，doxygen 開發團隊還在開發 XML 輸出）。

   (3) 圖形和圖標生成

　　在默認狀況下，Doxyfile 把 <CLASS_DIAGRAMS> 標記設置爲 Yes。這個標記用來生成類層次結構圖。要想生成更好的視圖，能夠從 Graphviz 下載站點 下載dot 工具。Doxyfile 中的如下標記用來生成圖表：

　　<CLASS_DIAGRAMS>：在 Doxyfile 中這個標記默認設置爲 Yes。若是這個標記設置爲 No，就不生成繼承層次結構圖。

　　<HAVE_DOT>：若是這個標記設置爲 Yes，doxygen 就使用 dot 工具生成更強大的圖形，好比幫助理解類成員及其數據結構的協做圖。注意，若是這個標記設置爲 Yes，<CLASS_DIAGRAMS> 標記就無效了。

　　<CLASS_GRAPH>：若是 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，就使用 dot 生成繼承層次結構圖，並且其外觀比只使用<CLASS_DIAGRAMS> 時更豐富。

　　<COLLABORATION_GRAPH>：若是 <HAVE_DOT> 標記和這個標記同時設置爲 Yes，doxygen 會生成協做圖（還有繼承圖），顯示各個類成員（即包含）及其繼

　　承層次結構。

   (4) 代碼文檔樣式　　

　　每一個代碼元素有兩種描述：簡短的和詳細的。簡短描述一般是單行的。函數和類方法還有第三種描述體內描述（in-body description），這種描述把在函數體中找到的全部註釋塊集中在一塊兒。比較經常使用的一些 doxygen 標記和註釋樣式以下：

• 簡短描述：使用單行的 C++ 註釋，或使用 <\brief> 標記。
• 詳細描述：使用 JavaDoc 式的註釋 /** … test … */（注意開頭的兩個星號 [*]）或 Qt 式的註釋 /*! … text … */。
• 體內描述：類、結構、聯合體和名稱空間等 C++ 元素都有本身的標記，好比 <\class>、<\struct>、<\union> 和 <\namespace>。

　　爲了爲全局函數、變量和枚舉類型生成文檔，必須先對對應的文件使用 <\file> 標記。清單 12 給出的示例包含用於四種元素的標記：函數標記（<\fn>）、函數參數標記（<\param>）、變量名標記（<\var>）、用於 #define 的標記（<\def>）以及用來表示與一個代碼片斷相關的問題的標記（<\warning>）。

　　一下是一些doxygen自建的命令，能夠在代碼註釋中加入

　　@addtogroup 添加到一個組。
　　@brief  概要信息
　　@deprecated 已廢棄函數
　　@details  詳細描述
　　@note  開始一個段落，用來描述一些注意事項
　　@par  開始一個段落，段落名稱描述由你本身指定
　　@param  標記一個參數的意義
　　@code .. @endcode 包含一段代碼
　　@fn  函數說明
　　@ingroup 加入到一個組
　　@return  描述返回意義
　　@retval  描述返回值意義
　　@include 包含文件

3. 其餘

doxygen功能仍是很強大的，對於c++和java的代碼結構生成以及圖標生成很好用;能夠很方便的看到代碼結構，對於c暫時沒有生成出對應的圖表，後續還須要繼續研究下。 後續get到其餘技能繼續在後面補充