JavaDoc類型：

/**

* ... 程序注釋 ...

*/

Qt類型：

/*!

* ... 程序注釋...

*/    

單行型式：

/// 這是一個簡潔型的注釋

//! 這也是一個簡潔型的注釋

用Doxygen的這幾種基本注釋類型就可以建立足以建立文檔了，如果需要更多復雜功能，Doxygen還可以提供高級格式如組（group）和列表。

Doxygen的常用注釋參數：

Doxygen的使用，如下：

E:\>xstring目錄包含下列文件：

Xstring.cpp

Xstring.h

其中xstring.h里對xstring類的StrToInt方法的注釋如下：

       /**

       *

0. 序言
為代碼寫注釋一直是大多數程序員有些困擾的事情。當前程序員都能接受為了程序的可維護性、可讀性編碼的同時寫注釋的說法，但對哪些地方應該寫注釋，注釋如何寫，寫多少等這些問題，很多程序員仍然沒有答案。更頭痛的是寫文檔，以及維護文檔的問題，開發人員通?？梢匀淌芫帉懟蛘吒膭哟a時編寫或者修改對應的注釋，但之后需要修正相應的文檔卻比較困難。如果能從注釋直接轉化成文檔，對開發人員無疑是一種福音。而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文檔系統。而國內的開發人員卻使用的不多，這里從開發人員使用的角度介紹這個工具，使開發人員用最少的代價盡快掌握這種技術，并結合這個工具探討如何撰寫注釋的問題。以下以linux下的C++語言為例進行介紹，以下討論基于doxygen1.3.3。

1. doxygen使用步驟
由于只是工具的使用，這里不介紹它的原理，直接從使用步驟開始。Doxygen的使用步驟非常簡單。主要可以分為：
1）第一次使用需要安裝doxygen的程序
2）生成doxygen配置文件
3）編碼時，按照某種格式編寫注釋
4）生成對應文檔
doxygen的安裝非常簡單， linux下可以直接下載安裝包運行即可，下載源代碼編譯安裝也是比較通用的編譯安裝命令。請參考其安裝文檔完成安裝。

Doxygen在生成文檔時可以定義項目屬性以及文檔生成過程中的很多選項，使用下面命令能夠產生一個缺省的配置文件：
doxygen -g [配置文件名]
可以根據項目的具體需求修改配置文件中對應的項，具體的修改過程在下面介紹。修改過的配置文件可以作為以后項目的模板。

讓doxygen自動產生文檔，平常的注釋風格可不行，需要遵循doxygen自己的格式。具體如何寫doxygen認識的注釋在第3節詳細介紹。

OK，代碼編完了，注釋也按照格式寫好了，最后的文檔是如何的哪？非常簡單，運行下面的命令，相應的文檔就會產生在指定的目錄中。
   doxygen [配置文件名]

需要注意的是doxygen并不處理所有的注釋，doxygen重點關注與程序結構有關的注釋，比如：文件、類、結構、函數、變量、宏等注釋，而忽略函數內變量、代碼等的注釋。

2. doxygen配置文件
doxygen配置文件的格式是也是通常的unix下配置文件的格式：注釋'#'開始；tag = value [,value2…]；對于多值的情況可以使用 tag += value [,value2…]。

對doxygen的配置文件的修改分為兩類：一種就是輸出選項，控制如何解釋源代碼、如何輸出；一種就是項目相關的信息，比如項目名稱、源代碼目錄、輸出文檔目錄等。對于第一種設置好后，通常所有項目可以共用一份配置，而后一種是每個項目必須設置的。下面選擇重要的，有可能需要修改的選項進行解釋說明，其他選項在配置文件都有詳細解釋。

TAG 缺省值 含義
PROJECT_NAME   項目名稱
PROJECT_NUMBER   可以理解為版本信息
OUTPUT_DIRECTORY   輸出文件到的目錄，相對目錄（doxygen運行目錄）或者絕對目錄
INPUT   代碼文件或者代碼所在目錄，使用空格分割
FILE_PATTERNS *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl 指定INPUT的目錄中特定文件，如：*.cpp *.c *.h 
RECURSIVE NO 是否遞歸INPUT中目錄的子目錄
EXCLUDE   在INPUT目錄中需要忽略的子目錄
EXCLUDE_PATTERNS   明確指定的在INPUT目錄中需要忽略的文件，如：FromOut*.cpp
  
OUTPUT_LANGUAGE English 生成文檔的語言，當前支持2、30種語言，國內用戶可以設置為Chinese
USE_WINDOWS_ENCODING YES（win版本）
NO（unix版本） 編碼格式，默認即可。
EXTRACT_ALL NO 為NO，只解釋有doxygen格式注釋的代碼；為YES，解析所有代碼，即使沒有注釋。類的私有成員和所有的靜態項由EXTRACT_PRIVATE和 EXTRACT_STATIC控制
EXTRACT_PRIVATE NO 是否解析類的私有成員
EXTRACT_STATIC NO 是否解析靜態項
EXTRACT_LOCAL_CLASSES YES 是否解析源文件（cpp文件）中定義的類
SOURCE_BROWSER NO 如果為YES，源代碼文件會被包含在文檔中
INLINE_SOURCES NO 如果為YES，函數和類的實現代碼被包含在文檔中
ALPHABETICAL_INDEX NO 生成一個字母序的列表，有很多類、結構等項時建議設為YES
GENERATE_HTML YES 是否生成HTML格式文檔
GENERATE_HTMLHELP NO 是否生成壓縮HTML格式文檔（.chm）
GENERATE_LATEX YES 是否乘車latex格式的文檔
GENERATE_RTF NO 是否生成RTF格式的文檔
GENERATE_MAN NO 是否生成man格式文檔
GENERATE_XML NO 是否生成XML格式文檔
  

3. doxygen注釋
3.1 注釋風格
下面是工作量最大部分，安裝doxygen格式寫注釋。通常代碼可以附上一個注釋塊來對代碼進行解釋，一個注釋塊由一行或者多行組成。通常一個注釋塊包括一個簡要說明（brief）和一個詳細說明（detailed），這兩部分都是可選的?？梢杂卸喾N方式標識出doxygen可識別的注釋塊。
1）JavaDoc類型的多行注釋。
/**
* ….text….
*/
2）QT樣式的多行注釋。
/*!
….text….
*/
3） /// …text….
4） //! …text….
簡要說明有多種方式標識，這里推薦使用@brief命令強制說明，例如：
/**
* @brief [some brief description ]
*      [ brief description more. ]
* 
* [some more detailed description…]
*/
以上這些注釋格式用來對緊跟其后的代碼進行注釋。doxygen也允許把注釋放到代碼后面，具體格式是放一個'<'到注釋開始部分。例如：
int var1 ; /**< ….text…. */
int var2; ///< ….text….

注釋和代碼完全分離，放在其他地方也是允許的，但需要使用特殊的命令加上名稱或者聲明進行標識，比如：class、struct、union、enum、fn、var、def、file、namespace、package、interface（這些也就是doxygen關注的注釋類型）。這里不推薦使用，建議注釋盡量放在代碼前后。具體使用方式參見doxygen手冊。

3.2 doxygen常用注釋格式
通常的選擇上面的一、兩種注釋風格，遇到頭文件中各種類型定義，關鍵變量、宏的定義，在其前或者后使用 @brief 定義其簡要說明，空一行后繼續寫其詳細的注釋即可。

對函數的注釋，是比較常常需要注釋的部分。除了定義其簡要說明以及詳細注釋，還可以使用param命令對其各個參數進行注釋，使用return命令對返回值進行注釋。常見的格式如下：
/**
*@brief func's brief comment.
*
* Some detailed comment.
*@param a [param a 's comment.]
*@param b [param b 's comment.]
*@exception std::out_of_range [exception's comment.]
*@return [return's comment.]
*/
int func1(int a, int b);

進行設計時，通常有模塊的概念，一個模塊可能有多個類或者函數組成，完成某個特定功能的代碼的集合。如何對這個概念進行注釋？doxygen提供了group的概念，生成的模塊的注釋會單獨放在一個模塊的頁面中。使用下面的格式定義一個group。
/** [group_name] [brief group description ]
* detailed group description ]
* @{
*/
code
/** @} */
group中的代碼可以有自己的注釋。單純定義一個模塊，去除{ 和}命令即可。任何其他代碼項（比如類、函數、甚至文件）如果要加入到某個模塊，可以在其doxygen注釋中使用ingroup命令即可。Group之間使用ingroup命令，可以組成樹狀關系。
/** @file util.cpp 
* @ingroup [group_name]
* @brief file's brief info.
*/
把多個代碼項一起添加到某個模塊中可以使用addtogroup命令，格式和defgroup相似。

對于某幾個功能類似的代碼項（比如類、函數、變量）等，如果希望一起添加注釋，而又不想提升到模塊的概念，可以通過下面的方式：
//@{
/** Comments for all below code. */
code…
//@}
對這種組進行命名可以使用name命令。此時中間代碼可以有自己的注釋。如：
/** @name group_name
* description for group.
*/
//@{
code…
//@}

3.3 doxygen常用注釋命令
doxygen通過注釋命令識別注釋中需要特殊處理的注釋，比如函數的參數、返回值進行突出顯示。上面也提到了一些注釋命令（如：brief、param、return、以及group相關的命令），下面對其他一些常用的注釋命令進行解釋說明。
@exception <exception-object> {exception description} 對一個異常對象進行注釋。
@warning {warning message } 一些需要注意的事情
@todo { things to be done } 對將要做的事情進行注釋
@see {comment with reference to other items } 一段包含其他部分引用的注釋，中間包含對其他代碼項的名稱，自動產生對其的引用鏈接。
@relates <name> 通常用做把非成員函數的注釋文檔包含在類的說明文檔中。
@since {text} 通常用來說明從什么版本、時間寫此部分代碼。
@deprecated
@pre { description of the precondition } 用來說明代碼項的前提條件。
@post { description of the postcondition } 用來說明代碼項之后的使用條件。
@code 在注釋中開始說明一段代碼，直到@endcode命令。
@endcode 注釋中代碼段的結束。

到此為止，常用的doxygen的注釋格式討論完畢，我們能夠按照一定的格式撰寫doxygen認識的注釋，并能夠使用doxygen方便快捷的生成對應的文檔，不過注釋中應該寫些什么，如何撰寫有效的注釋可能是困擾開發人員的一個更深層次的問題。

4. 注釋的書寫
注釋應該怎么寫，寫多還是寫少。過多的注釋甚至會干擾對代碼的閱讀。寫注釋的一個總的原則就是注釋應該盡量用來表明作者的意圖，至少也應該是對一部分代碼的總結，而不應該是對代碼的重復或者解釋。對代碼的重復或者解釋的代碼，看代碼可能更容易理解。反映作者意圖的注釋解釋代碼的目的，從解決問題的層次上進行注釋，而代碼總結性注釋則是從問題的解答的層次上進行注釋。

推薦的寫注釋的過程是首先使用注釋勾勒出代碼的主要框架，然后根據注釋撰寫相應的代碼。對各種主要的數據結構、輸出的函數、多個函數公用的變量進行詳細地注釋。對代碼中控制結構，單一目的的語句集進行注釋。下面是一些寫注釋時需要注意的要點：
   避免對單獨語句進行注釋；
   通過注釋解釋為什么這么做、或者要做什么，使代碼的讀者可以只閱讀注釋理解代碼；
   對讀者可能會有疑問的地方進行注釋；
   對數據定義進行注釋，而不是對其使用過程進行注釋；
   對于難于理解的代碼，進行改寫，而不要試圖通過注釋加以說明；
   對關鍵的控制結構進行注釋；
   對數據和函數的邊界、使用前提等進行注釋；

      雖然使用各種IDE或者Source Insight 可以方便地在windows下閱讀和分析C/C++代碼，但是一步步Go to Definetion 實在令人痛苦。Doxygen能夠生成函數調用關系圖，所有的函數調用關系可以一目了然，另外他還能統計文檔中所有的類，成員變量，成員函數等?？偟膩碚f，Doxygen不但能從局部把握代碼，還能從全局審視代碼，后者是一般IDE和Source Insight 不能做到的。所以，使用doxygen閱讀分析代碼可以達到事半功倍的效果。

          doxygen的安裝很簡單，到官方網站下載doxygen的windows安裝程序即可。除了安裝doxygen外，還需要安裝graphviz，因為doxygen需要使用graphviz的dot.exe生成調用圖。graphviz在它的官方網站上也可以下載到安裝程序。不過我下載的安裝程序在安裝時老是報cab文件錯誤。最后我下載了graphviz的release文件，即安裝程序下面的zip壓縮文件，下載完成后解壓縮即可。

         安裝完doxygen后即可進行適當的配置，然后運行doxyfile生成文檔?；镜呐渲们叭嗽缬姓f明，不再贅述。需要注意的是：

        1.要勾選Dot選項卡下面的HAVE_DOT、CALL_GRAPH 、CALLER_GRAPH 選項。并在DOT_PATH下面填入dot.exe的路徑，也就是graphviz安裝目錄下的bin文件夾。

        2.勾選Wizard->Project選項卡下面的Scan recursively！

        3.勾選Build選項卡下面的EXTRACT_ALL、EXTRACT_PRIVATE、EXTRACT_STATIC、EXTRACT_LOCAL_CLASSES、EXTRACT_LOCAL_METHODS選項

        4.如果程序里面有中文，將Project選項卡下的DOXYFILE_ENCODING和Input選項卡下面的INPUT_ENCODING改為GBK

       5.可以勾掉LATEX輸出，這樣節省編譯時間

5. 參考資料
1. doxygen homepage
http://www.stack.nl/~dimitri/doxygen/

2. doxygen manual 
http://www.stack.nl/~dimitri/doxygen/manual.html

3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4. 

4. 簡介doxygen
http://www.stack.nl/~dimitri/doxygen/doxygen_intro_cn.html

5. 10 Minutes to document your code
http://www.codeproject.com/tips/doxysetup.asp

6. 使用doxygen
http://www.csdn.net/Develop/article/16%5C16383.shtm