為代碼寫注釋一直是大多數程序員有些困擾的事情。當前程序員都能接受為了程序的可維護性、可讀性編碼的同時寫注釋的說法，但對哪些地方應該寫注釋， 注釋如何寫，寫多少等這些問題，很多程序員仍然沒有答案。更頭痛的是寫文檔，以及維護文檔的問題，開發人員通常可以忍受編寫或者改動代碼時編寫或者修改對 應的注釋，但之後需要修正相應的文檔卻比較困難。如果能從注釋直接轉化成文檔，對開發人員無疑是一種福音。而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在生成文檔時可以定義項目屬性以及文檔生成過程中的很多選項，使用下麵命令能夠產生一個缺省的配置文件： 讓doxygen自動產生文檔，平常的注釋風格可不行，需要遵循doxygen自己的格式。具體如何寫doxygen認識的注釋在第3節詳細介紹。 OK，代碼編完了，注釋也按照格式寫好了，最後的文檔是如何的哪？非常簡單，運行下麵的命令，相應的文檔就會產生在指定的目錄中。 需要注意的是doxygen並不處理所有的注釋，doxygen重點關注與程序結構有關的注釋，比如：文件、類、結構、函數、變量、宏等注釋，而忽略函數內變量、代碼等的注釋。 2. doxygen配置文件 對doxygen的配置文件的修改分為兩類：一種就是輸出選項，控製如何解釋源代碼、如何輸出；一種就是項目相關的信息，比如項目名稱、源代碼目 錄、輸出文檔目錄等。對於第一種設置好後，通常所有項目可以共用一份配置，而後一種是每個項目必須設置的。下麵選擇重要的，有可能需要修改的選項進行解釋 說明，其他選項在配置文件都有詳細解釋。 TAG 缺省值 含義 3. doxygen注釋 注釋和代碼完全分離，放在其他地方也是允許的，但需要使用特殊的命令加上名稱或者聲明進行標識，比如：class、struct、union、 enum、fn、var、def、file、namespace、package、interface（這些也就是doxygen關注的注釋類型）。這裏 不推薦使用，建議注釋盡量放在代碼前後。具體使用方式參見doxygen手冊。 3.2 doxygen常用注釋格式 對函數的注釋，是比較常常需要注釋的部分。除了定義其簡要說明以及詳細注釋，還可以使用param命令對其各個參數進行注釋，使用return命令對返回值進行注釋。常見的格式如下： 進行設計時，通常有模塊的概念，一個模塊可能有多個類或者函數組成，完成某個特定功能的代碼的集合。如何對這個概念進行注釋？doxygen提供了group的概念，生成的模塊的注釋會單獨放在一個模塊的頁麵中。使用下麵的格式定義一個group。 對於某幾個功能類似的代碼項（比如類、函數、變量）等，如果希望一起添加注釋，而又不想提升到模塊的概念，可以通過下麵的方式： 3.3 doxygen常用注釋命令 到此為止，常用的doxygen的注釋格式討論完畢，我們能夠按照一定的格式撰寫doxygen認識的注釋，並能夠使用doxygen方便快捷的生成對應的文檔，不過注釋中應該寫些什麽，如何撰寫有效的注釋可能是困擾開發人員的一個更深層次的問題。 4. 注釋的書寫 推薦的寫注釋的過程是首先使用注釋勾勒出代碼的主要框架，然後根據注釋撰寫相應的代碼。對各種主要的數據結構、輸出的函數、多個函數公用的變量進行詳細地注釋。對代碼中控製結構，單一目的的語句集進行注釋。下麵是一些寫注釋時需要注意的要點： 5. 參考資料 2. doxygen manual 3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4. 6. 使用doxygen |
doxygen使用詳解
youwire (2010-12-21 20:33:13) 評論 (0)為代碼寫注釋一直是大多數程序員有些困擾的事情。當前程序員都能接受為了程序的可維護性、可讀性編碼的同時寫注釋的說法，但對哪些地方應該寫注釋， 注釋如何寫，寫多少等這些問題，很多程序員仍然沒有答案。更頭痛的是寫文檔，以及維護文檔的問題，開發人員通常可以忍受編寫或者改動代碼時編寫或者修改對 應的注釋，但之後需要修正相應的文檔卻比較困難。如果能從注釋直接轉化成文檔，對開發人員無疑是一種福音。而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在生成文檔時可以定義項目屬性以及文檔生成過程中的很多選項，使用下麵命令能夠產生一個缺省的配置文件： 讓doxygen自動產生文檔，平常的注釋風格可不行，需要遵循doxygen自己的格式。具體如何寫doxygen認識的注釋在第3節詳細介紹。 OK，代碼編完了，注釋也按照格式寫好了，最後的文檔是如何的哪？非常簡單，運行下麵的命令，相應的文檔就會產生在指定的目錄中。 需要注意的是doxygen並不處理所有的注釋，doxygen重點關注與程序結構有關的注釋，比如：文件、類、結構、函數、變量、宏等注釋，而忽略函數內變量、代碼等的注釋。 2. doxygen配置文件 對doxygen的配置文件的修改分為兩類：一種就是輸出選項，控製如何解釋源代碼、如何輸出；一種就是項目相關的信息，比如項目名稱、源代碼目 錄、輸出文檔目錄等。對於第一種設置好後，通常所有項目可以共用一份配置，而後一種是每個項目必須設置的。下麵選擇重要的，有可能需要修改的選項進行解釋 說明，其他選項在配置文件都有詳細解釋。 TAG 缺省值 含義 3. doxygen注釋 注釋和代碼完全分離，放在其他地方也是允許的，但需要使用特殊的命令加上名稱或者聲明進行標識，比如：class、struct、union、 enum、fn、var、def、file、namespace、package、interface（這些也就是doxygen關注的注釋類型）。這裏 不推薦使用，建議注釋盡量放在代碼前後。具體使用方式參見doxygen手冊。 3.2 doxygen常用注釋格式 對函數的注釋，是比較常常需要注釋的部分。除了定義其簡要說明以及詳細注釋，還可以使用param命令對其各個參數進行注釋，使用return命令對返回值進行注釋。常見的格式如下： 進行設計時，通常有模塊的概念，一個模塊可能有多個類或者函數組成，完成某個特定功能的代碼的集合。如何對這個概念進行注釋？doxygen提供了group的概念，生成的模塊的注釋會單獨放在一個模塊的頁麵中。使用下麵的格式定義一個group。 對於某幾個功能類似的代碼項（比如類、函數、變量）等，如果希望一起添加注釋，而又不想提升到模塊的概念，可以通過下麵的方式： 3.3 doxygen常用注釋命令 到此為止，常用的doxygen的注釋格式討論完畢，我們能夠按照一定的格式撰寫doxygen認識的注釋，並能夠使用doxygen方便快捷的生成對應的文檔，不過注釋中應該寫些什麽，如何撰寫有效的注釋可能是困擾開發人員的一個更深層次的問題。 4. 注釋的書寫 推薦的寫注釋的過程是首先使用注釋勾勒出代碼的主要框架，然後根據注釋撰寫相應的代碼。對各種主要的數據結構、輸出的函數、多個函數公用的變量進行詳細地注釋。對代碼中控製結構，單一目的的語句集進行注釋。下麵是一些寫注釋時需要注意的要點： 5. 參考資料 2. doxygen manual 3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4. 6. 使用doxygen |