doxygen是一種從源代碼生成文檔的工具，支持多種語言。當然，源代碼中需按一定的格式寫註釋，這些註釋的格式也能幫助我們養成很好的註釋習慣，可以嘗試一下。
使用doxygen生成文檔的方法很簡單：
$ doxygen -g –s
$ doxygen
只需兩個簡單命令就可以了。
下面簡單說明一下：
1、在工程目錄下輸入doxygen –s –g doxyconfig，其中doxyconfig爲生成配置的文件名稱，可任意指定，如果不指定，默認生成的配置文件爲Doxyfile。man手冊中沒有詳細說明選項的意思，這裏不妨猜測一下，-s爲simple，-g爲generate，如果不指定-s，則生成的配置文件大約爲63KB，行數約1500左右；反之，則約成10KB，行數約250左右。——此處猜測便根據這些測試而來的。
2、生成配置文件後，會出現提示信息，大意是說那個配置文件已經生成了，現在編輯它，之後輸入doxygen Doxyfile(經實踐證明，可以只輸入doxygen命令)就可以產生工程的文檔了。如果再次使用doxygen生產配置文件，則原來的就配置文件就變成了備份文件，添加後綴名.bak。
3、根據doxygen要求的註釋格式來編寫代碼的註釋，這一步要求比較高，而且工作量比較大。我們在文章後面還要講解的。
下面介紹一下如何編輯生成的配置文件，我們以我們的串口程序爲例子。
doxygen的配置文件與大多數linux平臺的配置文件類似，就是一些關鍵字與值，配置文件中的值以YES和NO居多。
DOXYFILE_ENCODING = UTF-8，默認編碼爲UTF-8，這樣可以支持中文。
PROJECT_NAME = “SerialPort”，項目名稱，多個單詞需要使用引號(“”)。
PROJECT_NUMBER = “1.0 beta”，項目版本號。
OUTPUT_DIRECTORY = serialport-html，輸出文檔的目錄，如果爲空，表示在當前目錄，建議寫上表示本工程的有意義的目錄名稱，比如我們就指定目錄名稱爲serialport-html。
OUTPUT_LANGUAGE = English，文檔語言，可以指定爲Chinese。
IMAGE_PATH = image_dir，指定圖片存放的目錄，我們將圖片放到當前目錄下的image_dir目錄中，因爲我們的文檔會出現測試圖片示例。
HTML_OUTPUT= . ，html輸出目錄名稱，默認爲html目錄，如果爲“.”則表明爲上述OUTPUT_DIRECTORY目錄。
GENERATE_LATEX = NO，是否生成LaTeX，默認生成的，但我們不想生成。
好了，我們需要修改的就這麼多，使用上述第2步驟的命令就可以生成一個漂亮的文檔了。此外還有一些常用的設置選項。
INPUT =xxx，代碼文件或目錄，多個文件(目錄)需要以空格隔開，如果不指定，表示當前目錄，但是，如果指定目錄且當前目錄有代碼文件的話，需要使用點號(“.”)表示當前目錄。
FILE_PATTERNS=xxx，指定各種文件，我們常用爲*.cpp *.c *.h，等等。
上面基本就是我們常用的了，如果還想更深入瞭解，請移步到google網站。
下面就是真正需要花費一定時間的工作：爲我們的程序作特定格式的註釋。
doxygen支持多種註釋風格，比如JavaDoc風格，它在C語言塊註釋開始處再添加一個星號(*)構成，如下：
1. /**
2. * … text …
3. */
Qt風格：
1. /*!
2. * ... text ...
3. */
上面兩種方式中間的星號(*)是可選的，不過，個人認爲添加會更美觀一些。
C++風格的，——就是在C++註釋後面再添加“/”：
1. ///
2. /// ... text ...
3. ///
或者是這樣：
1. //!
2. //!... text ...
3. //!
經測試，實際使用中，如果是單行註釋的話，可以使用如下的格式：
1. /** ... text ... */
2. /**< ... text ... */
這些格式會被doxygen文檔化，如果不想讓它文檔化，可以“破壞”這些格式，比如可以使用“正宗”的C/C++註釋：
1. /* ... text ... */
2. // ... text ...
上述風格來自doxygen的manual頁面，具體地址爲：
http://www.stack.nl/~dimitri/doxygen/docblocks.html
下面介紹一下常用doxygen的命令，更多詳細使用說明，請參考如下地址：
http://www.stack.nl/~dimitri/doxygen/commands.html#cmde
doxygen命令以@或開始，兩種方式均可以。文中以@標記之。
@def 宏定義說明
@fn 函數 函數說明
@param 參數 參數說明
@return 返回值說明(出錯返回什麼值，等等)
@file 文件名
@author 作者
@version 程序版本
@date 日期
@note 註解(注意事項，等)
@warning 警告信息
@bug bug信息
@test 測試示例、信息
@todo 一些未完事宜
(@bug、@test以及@todo等會出現鏈接頁面)
上面這樣適合在函數、文件前面出現。
下面爲生成特殊字體的命令：
@a @e @em：其後的單個字(word)表現爲斜體，以強調作用。如有多個word的話，使用<em>xxx xxx</em>代替。
@b：其後的word爲粗體，多個則使用<b>xxx xxx</b>。
@c @p：字體表現爲打印機字體，多個則使用<tt>xxx xxx</tt>。
下面是一些具體的實例。
在文件開始處的版權聲明及其它信息：
/**
* Copyleft (C) 2010 Late Lee
* This program is tested on LINUX PLATFORM, WITH GCC 4.x.
* The program is distributed in the hope that it will be
* useful, but WITHOUT ANY WARRANTY. Please feel free to
* use the program, and I feel free to ignore the related
* issues. Any questions or suggestions, or bugs, please
* contact me at or e-mail to
* if you want to do this.
* @file serialport.c
* @author Late Lee
* @date Mon Jan 10 2011
*
* @brief Some utils of the serial port, such as open the port, close
* the port and setup the port.
* @note This is a note.
* @warning This is a warning.
* @bug This is a bug.
*/
在函數前的註釋：
/**
* open_port – Open a serial port
*
* @param port : The port number, eg, open_port(1) will open com1
*
* @return Return fd if success, otherwise will return -1 with some msg.
*/
定義宏使用的註釋：
/**
* @def error_exit
* @brief A macro that prints the @a error msg and exit.
*/
#define error_exit(error)
do{
fprintf(stderr, “%sn”, error);
exit(0);
} while(0)
或者你會說，這樣的註釋風格太麻煩了！不怕！現在有了跟emacs結合的doxymacs，在emacs中配置了doxymacs，這些註釋是十分方便的！比如需要在文件前插入註釋，按C-c d i即可，在函數前插入註釋，按C-c d f即可，等等。具體的請移步到這裏的文章：http://www.latelee.org/embedded-linux/learning-elinux-4-my-emacs-ii及http://www.latelee.org/embedded-linux/learning-elinux-4-my-emacs。如果你使用的不是emacs，那Sorry，我也不太會，如果你懂，不妨分享一下。
這個串口程序的文檔已經放到網站上了，這裏main.c文件參考頁面地址：http://www.latelee.org/yetanothertest/serialport-html-cn/main_8c.html
此外，我們還測試生成中文文檔，因此doxygen使用UTF8，因此只要將代碼文件保存爲utf8編碼即可(使用Ultra Edit或notepad++等等編輯器很容易做到)。但這又引出一個問題，gcc並不支持utf8！經過google，發現gcc 4.4.0版本以後已經支持utf8了，因此，爲了做這個測試，花了一個小時左右編譯、安裝高版本的gcc(我們使用4.4.5版本)，結果，這個版本的gcc是支持utf8的。後來，又發現，如果使用“UTF-8 無BOM格式編碼”格式保存源文件的話，在原來的gcc下也編譯通過。因此如果想在程序中使用中文註釋，建議以此格式保存，當然，在系統的locale不是中文的情況下看到的中文是亂碼的。
1、盡信書則不如無書，我們建議各位到實踐中試一試，這樣學到的知識才是我們自己的，比如，在指定源代碼目錄中，我的測試文件main.c放在當前目錄下，如果不指定“.”的話，doxygen便不會處理該文件，這是網上很多資料沒有說明的，因此需要實踐才能瞭解。
2、我們強烈建議各位到官方網站學習，因爲其它地方絕大部分都出自官方網站，manual頁面地址是：