程式師世界 >> 編程語言 >> 網頁編程 >> PHP編程 >> 關於PHP編程 >> 【原創】利用doxygen來管理項目文檔或注釋，doxygen項目

【原創】利用doxygen來管理項目文檔或注釋，doxygen項目

編輯：關於PHP編程

【原創】利用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的配置文件裡面可以指定日志文件的路徑。你可以好好利用這個日子文件，用相應的腳本語言寫一小段代碼來分析這個日志文件，然後人性化點展示到web頁面上面。指定的管理人員定期的去查看下注釋錯誤日志，即可即時糾正不對的注釋內容。