【原創】利用doxygen來管理項目文檔或注釋，doxygen項目
一、doxygen應用情境：
doxygen可以用來管理目前主流的程式設計語言的注釋而形成文檔系統。（包括C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran等）。doxygen官網地址（http://www.doxygen.nl/）近來大部分時間花在api介面的維護上面，其中比較重要的一個環節就是你寫的介面如何讓調用者一目瞭然的理解用法。不管是內部無線服務端與用戶端之間的配合，還是對外開放的API介面，都一樣。花了幾天時間嘗試了下使用doxygen結合svn hook來管理介面文檔還是很方便實用的。doxygen官網自己本身其實就是利用doxygen來做的，如果大家想要看更具體的效果，就可以直接參考http://www.doxygen.nl/。
以下先貼出我自己做出來的部分，UI很挫，大家真正使用時可以讓公司UI部門美化下，由於我目前還主要是內網使用，因此沒有去過多考慮UI體驗：
二、安裝：
doxygen目前已經比較全面的支援了windows、mac ox、linux等主流系統。而且基本上使用於目前所有的主流程式設計語言。這裡簡要介紹下自己在ubuntu系統下面的源碼編譯安裝過程。其餘安裝方法可以參考官網。
三、使用doxygen之設定檔的配置：
doxygen的使用可以說就是對設定檔的配置，就是說，你只要稍微配置一下設定檔，再執行一下命令： xxxx/doxygen xxxx.conf 就可以產生你想要的文檔（這裡doxygen提供了多種格式的文檔，我主要用的是html的，這樣我們可以自己配置一個web服務到這個html上面，就可以再web上面使用文檔了。），doxygen提供了200多個配置項，通過設定檔就已經可以完成豐富的功能了，下面舉一些常用的配置說明：
- 利用命令xxx/doxygen -g 就會在目前的目錄下面產生一個預設設定檔 doxygen.conf。開啟預設設定檔，你會發現裡面每一個配置項都是 配置名 配置值 這樣的key-value格式，如果你有一定的英文功底的話，配置基本上就不是什麼問題了。
- 配置的詳細說明請參考：http://www.stack.nl/~dimitri/doxygen/manual/config.html
- ABBREVIATE_BRIEF //簡短摘要
- ALIASES //別名
- ALLEXTERNALS //所有外部文檔
- ALPHABETICAL_INDEX //字母順序索引
- ALWAYS_DETAILED_SEC //詳細描述部分
- BINARY_TOC //二進位操作
- BRIEF_MEMBER_DESC //簡短的成員描述
- CALL_GRAPH //調用到的圖
- CASE_SENSE_NAMES //檢測的範例的名字
- CHM_FILE //CHM格式檔案
- CLASS_DIAGRAMS //類-表
- CLASS_GRAPH //類-圖
- DOT_PATH //DOT路徑設定
- DOT_TRANSPARENT //DOT轉換設定
- DOTFILE_DIRS //DOTFILE 列表顯示
- ENABLE_PREPROCESSING //允許"預先處理"指令
- ENUM_VALUES_PER_LINE //每行的枚舉值
- ENABLED_SECTIONS //允許分段顯示
- EXAMPLE_PATH //例子路徑
- EXAMPLE_PATTERNS //例子用的檔案格式（*.cpp, *.h , *.java等）
- EXAMPLE_RECURSIVE //例子遞迴
- COLLABORATION_GRAPH //相互呼叫歷程圖
- COLS_IN_ALPHA_INDEX //以列形式顯示的字母順序的索引
- COMPACT_LATEX //壓縮的LATEX文檔
- COMPACT_RTF //壓縮的RTF文檔
- CREATE_SUBDIRS //建立一個"子目錄"
- DETAILS_AT_TOP //文檔的詳細頭部
- DIRECTORY_GRAPH //目錄圖
- DISABLE_INDEX //禁用INDEX
- DISTRIBUTE_GROUP_DOC //禁用文檔成組顯示
- DOT_IMAGE_FORMAT //點陣圖形
- DOT_MULTI_TARGETS //多個DOT目標
- EXCLUDE //可執行檔
- EXCLUDE_PATTERNS //可執行檔格式（*.exe, *.dll等）
- EXCLUDE_SYMLINKS //可執行檔SYMLINKS
- EXPAND_AS_DEFINED //規定的擴充
- EXPAND_ONLY_PREDEF //預定義擴充
- EXTERNAL_GROUPS //使用到的外部的檔案
- EXTRA_PACKAGES //使用到的外部外掛程式包
- EXTRACT_ALL //提取所有
- EXTRACT_LOCAL_CLASSES //提取所有本地類
- EXTRACT_LOCAL_METHODS //提取所有本地方法
- EXTRACT_PRIVATE //提取所有private
- EXTRACT_STATIC //提取所有static
- FILE_PATTERNS //檔案路徑
- FILE_VERSION_FILTER //檔案版本控制
- FILTER_PATTERNS //控制格式（主要版本：第1次版本：第2次版本號碼）
- FILTER_SOURCE_FILES //原檔案的版本控制
- FULL_PATH_NAMES //全路徑名
- GENERATE_AUTOGEN_DEF //產生自動定義檔案形式
- GENERATE_BUGLIST //產生BUG列表
- GENERATE_CHI //產生"希臘字母"
- GENERATE_DEPRECIATEDLIST //產生"評估"列表
- GENERATE_HTML //產生HTML
- GENERATE_HTMLHELP //產生HTMLHELP
- GENERATE_LATEX //產生LATEX
- GENERATE_LEGEND //產生圖例
- GENERATE_MAN //產生MAN檔案
- GENERATE_PERLMOD //產生Perl指令碼
- GENERATE_RTF //產生RTF
- GENERATE_TAGFILE //產生標誌檔案
- GENERATE_TESTLIST //產生TESTLIST
- GENERATE_TODOLIST //產生TODOLIST
- GENERATE_TREEVIEW //產生樹狀檢視顯示
- GENERATE_XML //產生XML
- GRAPHICAL_HIERARCHY //繼承圖表
- GROUP_GRAPHS //組-圖
- HAVE_DOT //隱藏DOT
- HHC_LOCATION //隱藏位置
- HIDE_FRIEND_COMPOUNDS //隱藏"複合的"友員類型
- HIDE_IN_BODY_DOCS //隱藏文檔的主體
- HIDE_SCOPE_NAMES //隱藏"範圍"名
- HIDE_UNDOC_CLASSES //隱藏"未歸檔"的所有CLASS
- HIDE_UNDOC_MEMBERS //隱藏"未歸檔"的所有的成員
- HIDE_UNDOC_RELATIONS //隱藏"未歸檔"的關係
- HTML_ALIGN_MEMBERS //HTML文檔中成員對齊
- HTML_FOOTER //HTML腳註設定
- HTML_HEADER //HTML頭部設定
- HTML_OUTPUT //HTML輸出設定
- HTML_STYLESHEET //HTML樣式設定
- IGNORE_PREFIX //忽略哪些首碼
- IMAGE_PATH //圖片的路徑設定
- INCLUDE_GRAPH //包含-圖
- INCLUDE_PATH //標頭檔包含的路徑
- INHERIT_DOCS //文檔的繼承關係
- INLINE_INFO //內聯信
- INLINE_INHERITED_MEMB //通過"繼承"得到的內聯成員
- INLINE_SOURCES //內聯部分的原始碼
- INPUT //輸入設定
- INPUT_FILTER //能夠接受的輸入檔案的副檔名格式設定（重要）
- INTERNAL_DOCS //內部文檔
- JAVADOC_AUTOBRIEF //JAVADOC工具產生的文檔的"自動摘要"
- LATEX_BATCHMODE //LATEX匹配方式
- LATEX_CMD_NAME //LATEX 命令名
- LATEX_HEADER //LATEX 頭部
- LATEX_HIDE_INDICES //LATEX內部隱藏的包含
- LATEX_OUTPUT //LATEX輸出
- MACRO_EXPANSION //宏展開設定（重要）
- MAKEINDEX_CMD_NAME //MAKEINDEX命令索引
- MAN_EXTENSION //MAN擴充
- MAN_LINKS //MAN 連結設定
- MAN_OUTPUT //MAN輸出設定
- MAX_DOT_GRAPH_DEPTH //DOT圖的最大深度
- MAX_DOT_GRAPH_HEIGHT //DOT圖的最大高度
- MAX_DOT_GRAPH_WIDTH //DOT圖的最大寬度
- MAX_INITIALIZER_LINES //最大初始化行
- MULTILINE_CPP_IS_BRIEF //多 個CPP檔案的簡短描述
- MULTILINE_CPP_IS_BRIEF //多 個CPP檔案的簡短描述
- OPTIMIZE_OUTPUT_FOR_C //對C採用的最佳化設定
- OPTIMIZE_OUTPUT_JAVA //對JAVA採用的最佳化設定
- OUTPUT_DIRECTORY //輸出路徑設定（重要）
- OUTPUT_LANGUAGE //輸出語言設定（重要）
- PAPER_TYPE //紙張類型
- PDF_HYPERLINKS //PDF格式超連結設定（重要）
- PERL_PATH //perl路徑設定
- PERLMOD_LATEX //perlmod LATEX
- PERLMOD_PRETTY // perlmod PRETTY（漂亮/相當）
- PERLMOD_MAKEVAR_PREFIX //perlmod MAKE檔案版本 PREFIX
- PREDEFINED //預先定義（重要）
- PROJECT_NAME //工程名（重要）
- PROJECT_NUMBER //工程的組成成員（重要）
- QUIET //靜態量設定（重要）
- RECURSIVE //遞迴和迴圈
- REFERENCED_BY_RELATION //交叉參考（重要）
- REFERENCES_RELATION //交叉參考的關係
- REPEAT_BRIEF //重新設定"簡短說明"為開啟狀態
- RTF_EXTENSIONS_FILE //RTF展開檔案
- RTF_HYPERLINKS //RTF超連結
- RTF_OUTPUT //RTF輸出設定
- RTF_STYLESHEET_FILE //RTF樣式檔案
- SEARCH_INCLUDES //搜尋時需要包含什麼（重要）
- SEARCHENGINE //搜尋引擎設定（重要）
- SHORT_NAMES //使短檔案名稱生效
- SHOW_DIRECTORIES //顯示目錄
- SHOW_INCLUDE_FILES //顯示包含檔案（一般NO，否則太大）
- SHOW_USED_FILES //顯示被用到的檔案（一般YES）
- SKIP_FUNCTION_MACROS //跳過函數中的宏（重要），菜鳥最好別跳
- SORT_BRIEF_DOCS //文檔的簡短摘要
- SORT_MEMBER_DOCS //成員的簡短描述
- SOURCE_BROWSER //原檔案瀏覽路徑
- STRIP_CODE_COMMENTS //排除哪些條碼形式注釋（重要）
- STRIP_FROM_INC_PATH //排除哪些標頭檔包含的注釋（重要）
- STRIP_FROM_PATH //排除哪些條碼路徑設定
- SUBGROUPING //子組設定（重要）
- TAB_SIZE //TAB符SIZE設定（重要）
- TAGFILES //標誌檔案
- TEMPLATE_RELATIONS //模板關係設定（重要）
- TOC_EXPAND //TOC擴充
- TREEVIEW_WIDTH //樹狀圖顯示的寬度設定（重要）
- UML_LOOK //UML外觀設定（重要）
- USE_WINDOWS_ENCODING //使用windows系統的編碼形式（重要）
- VERBATIM_HEADERS //VERBATIM頭部（標頭檔）
- WARN_FORMAT //警告格式指定（重要）
- WARN_IF_DOC_ERROR //如果文檔出錯則顯示警告
- WARN_IF_UNDOCUMENTED //如果是未歸檔檔案則顯示警告
- WARN_LOGFILE //警告記錄檔設定
- WARN_NO_PARAMDOC //無參數文檔警告形式設定
- WARNINGS //警告設定（重要）
- XML_DTD //XML檔案類型定義（重要）
- XML_OUTPUT //XML輸出設定（重要）
- XML_PROGRAMLISTING //XML程式列表（重要）
XML_SCHEMA //XML模式設定（重要）
四、doxygen配置完成後注釋的書寫
當你配置好doxygen後，今後你基本上的時間都是花在你代碼當中的注釋的書寫和維護。想要利用doxygen來管理文檔。那麼代碼的注釋就不需嚴格要求。
/** * @brief 這裡用brief來說明介面方法的主要功能 * @date 介面方法的建立時間 * @author 介面方法的建立人 * @param : 參數說明如下表： * name | type |description of param * ----------|-----------|-------------------- * car_id | int |車源編號 * province | int |業務員所在省份 * x | x | x * x | x | x * x | x | x * @return 傳回值說明如下： * name | type | description of value * -------- |----------|---------------------- * car_id | int | 車源編號 * car_info | object | json對象格式的車源資訊 * @warning 該介面需要告知給調用者看的一些警告 * @attention 該介面需要告知給調用者看的一些注意事項 * @note 該介面的一些備忘說明。通常用於當後者對該介面有較大改動的時候。備忘一下某個時間點某人改動了什麼東西 * @ todo 該介面的一些未完成的待辦內容 */public function newSale() { do someting; }
五、doxygen的比較常用的特性
doxygen的功能還遠遠不止我上面介紹的那些，還有很多豐富多彩的功能，有想要使用這東西的人，可以自己去doxygen官網上面學習下哈。本文可隨意轉載，但是請務必註明原文出處。
http://www.bkjia.com/PHPjc/922301.htmlwww.bkjia.comtruehttp://www.bkjia.com/PHPjc/922301.htmlTechArticle【原創】利用doxygen來管理項目文檔或注釋，doxygen項目 一、doxygen應用情境： doxygen可以用來管理目前主流的程式設計語言的注釋而形成文檔系統...
