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

時間 2019-11-17

標籤原創利用 doxygen 管理項目文檔註釋简体版

原文原文鏈接

1、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體驗：php

2、安裝：

doxygen目前已經比較全面的支持了windows、mac ox、linux等主流系統。並且基本上使用於目前全部的主流編程語言。這裏簡要介紹下本身在ubuntu系統下面的源碼編譯安裝過程。其他安裝方法能夠參考官網。

下載ubuntu14.04適用的doxygen源碼。官網當中download選項裏面有專門適用ubuntu的版本下載。下下來的源碼包命名格式大體如：doxygen-{doxygen版本號}.src.tar.gz 解壓。命令以下：css

gunzip doxygen-$VERSION.src.tar.gz 
tar xf doxygen-$VERSION.src.tar

環境檢查，要安裝doxygen，在ubuntu下面須要部分依賴的支持。進入解壓後的目錄裏面，裏面有個./configure 的shell腳本。執行命令：sh ./configure 進行安裝環境檢查，裏面會列出一些你當前系統已經知足要求的和缺乏的依賴。在ubuntu下面你能夠簡單的利用 sudo apt-get install xxxx（依賴名稱），來逐個把缺乏的依賴都裝上。這步也很快的。html
接下去就是、sudo make 和 sudo make install了。若是在make或者 make install的過程當中有提示缺乏什麼東西的話。sudo apt-get install xxx裝上便可。java
完事以後，在命令行下面試試看執行命令：doxygen --version 。若是出來版本號，說明已經安裝成功。linux
補充說明：關於make 和 make install。我我的比較喜歡直接make後使用源碼包裏面的 xxx/bin/doxygen 命令來生成文檔，而不去安裝。由於後期真正使用其來生成文檔的時候會發現咱們須要改掉裏面不少默認的東西（固然不改也是徹底能夠的，並不是不能用）。這個時候你能夠去找到剛纔解壓的源碼包裏面xxx/src/ 下面的源碼文件，找到執行對應功能模塊的.cpp文件（c++寫的源碼），你直接能夠本身去修改裏面的c++文件，而後從新用make編譯。這樣就能夠把doxygen改成任何你本身想要的效果。舉個簡單的例子：doxygen默認檢查你代碼後function都叫作函數。而在api接口中，我更但願一個function叫作一個接口，而不是叫作一個函數。其餘修改相似。c++

3、使用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模式設置（重要）web

4、doxygen配置完成後註釋的書寫

當你配置好doxygen後，從此你基本上的時間都是花在你代碼當中的註釋的書寫和維護。想要利用doxygen來管理文檔。那麼代碼的註釋就必需嚴格要求。

下面是我所用到的經常使用註釋的書寫要求，其餘的更多請參考：http://www.stack.nl/~dimitri/doxygen/manual/commands.html

/**
 * @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頁面上面。指定的管理人員按期的去查看下注釋錯誤日誌，便可即時糾正不對的註釋內容。面試

5、doxygen的比較經常使用的特性

markdown語法的使用，doxygen完美的支持全部markdown語法。你能夠在註釋中使用任何markdown語法。也能夠直接在項目doxygen配置文件中指定的INPUT路徑下面書寫md文件。你能夠把如何使用文檔？如何書寫註釋？等等一些公告內容用md文件來存放。這樣，每一個md文件就會再html文檔系統裏面獨立生成一個頁面。並在左側造成一個獨立的菜單。shell
別名的使用。利用配置文件裏面的ALIASES能夠設置註釋別名，在書寫註釋的過程當中，常常有些東西是必須寫，而又一成不變的東西可使用別名來簡化。詳見：http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html
因爲每次修改完代碼後，都須要用doxygen命令來從新生成文檔，文檔纔會更新。因此若是你的文檔對實時性的要求比較高的話，能夠考慮藉助公司內部的版本管理系統的hook來實現。我使用的是svn hook裏面的post-commit來實現，當程序員把本身書寫的代碼提交svn的時候，hook去自動從新執行doxygen命令來更新文檔。這樣就能作到文檔的實時更新，而不須要咱們碼農去作什麼。
生成後的文檔系統的左側菜單每每並不是咱們想要的結果。咱們但願改成一些咱們本身的鏈接或者咱們本身的顯示名稱。這事能夠利用配置文件裏面的LAYOUT_FILE = DoxygenLayout.xml （名稱能夠本身定，這是默認名稱）。執行命令 doxygen -l 會在當前目錄下面生成當前文檔的默認layout文件DoxygenLayout.xml，打開編輯DoxygenLayout.xml裏面的xml內容就能夠改變左側的菜單接口。具體本身研究了哈，這裏不細說。
header.html 和 footer.html 頁頭和頁尾的自定義。是否感受生成的文檔的界面並不那麼的盡如人意，嘗試本身寫個頁頭和頁尾。只是簡單的html，首先你要獲取到系統默認的header.html和footer.html，而後在默認的基礎上面修改。獲取默認header.html和footer.html和頁面css的命令爲：doxygen -w html new_header.html new_footer.html new_stylesheet.css YourConfigFile。
修改頁面的樣式，使其擁有更好的UI體驗。可使用配置文件中的 HTML_STYLESHEET 或者 HTML_EXTRA_STYLESHEET 來寫本身的樣式css文件或者擴展css文件。只須要在配置文件裏面把兩個配置指向你本身的css文件路徑便可。
製做一個你本身的Logo圖片，再把系統上面的按個默認的doxygen的logo給替換下就萬事大吉了。替換logo使用配置項：PROJECT_LOGO 。