關鍵詞：doxygen、Doxyfile、doxywizard、dot、graphviz等等。
使用doxygen從源碼注釋生成幫助文檔或者SDK，輸出格式有多種比如htmp、Latex等等。
如果想可視化頭文件關系、函數調用關系，可以生成dot格式的布局方式；然后使用graphviz的dot工具生成可視化關系圖。
這里面主要包括三部分：在代碼中添加doxygen規則注釋；生成doxygen配置文檔doxyfile；graphviz的dot布局可視化配置。
使用doxygen的優點：
1. 注釋緊跟代碼，一條命令生成響應SDK，快捷、及時更新，容易維護。
2. 加上dot之后，函數關系、類關系等更加明確，有利於理解代碼。
3. 輸出格式豐富，適合各種形式發布。
4. 不同Doxyfile輸出不同內容，適合對內對外發布。
0. 工具安裝
需要安裝doxygen、doxywizard、graphviz：
sudo apt install doxygen sudo apt install doxygen-gui sudo apt install graphviz graphviz-doc
1. doxygen介紹
關於doxygen的介紹在Doxygen Manual中有詳細的說明，包括user manual、reference manual和information for developers三部分。
下圖是doxygen信息流框圖，按照文件doxyfile的配置，doxygen從sources中解析注釋，輸出結果，結果可以使XML、Latex、HTML、PDF等等。
2. 配置doxygen
doxygen的使用方法通過doxygen -h可以獲取。
快速創建配置文件doxyfile的方式：
doxygen -s -g doxyfile--------------簡化版的doxyfile，沒有很多注釋信息。
doxygen -g doxyfile
上面的創建方式比較簡單，但是配置比較復雜。
doxygen-gui提供了doxywizard可視化配置工具。
doxywizard-----------------新建一個Doxyfile，並進行配置。
doxywizard Doxyfile--------從已有配置文件Doxyfile讀取配置。
第一步，設置doxygen工作目錄。
第二步，包括三部分分別是Wizard概要設置，Expert對功能進行專家模式設置，Run開始執行doxygen生成幫助文檔。
如果要用好doxygen，就需要對Expert詳細了解。
參考文檔：《Doxywizard usage》
3. 如何給代碼加doxygen注釋
在《Documenting the code》中詳細介紹了給不同語言添加注釋的方法。
常用的功能包括個文件添加注釋和函數添加注釋。
比如文件注釋：
/** * @file usb_hidraw_api.c * @author xxx * @brief 操作hidraw設備接口open/close/read/write. */
顯示結果如下：
添加函數注釋：
/** @brief 從hidraw設備讀取數據。 @param fd hidraw設備句柄。 @param r_buf 讀取函數緩存指針。 @param len 讀取大小。 @return 0: 讀取成功。\n -1: 讀取失敗。 */ int usb_read(int fd,char *r_buf,int len) { int ret; char tmp_buf[520]; if(r_buf == NULL) { perror("usb_read::pointer error!"); return -1; } ret = read(fd, tmp_buf, len+1); if(ret < 0) { //printf("read data error %d\n",ret); return -1; } memcpy(r_buf,&tmp_buf[1],len); return 0; }
結果如下：
更多增強功能參考官網文檔。
4. 使用graphviz的dot功能
使用graphviz的dot功能，可以生成詳細的函數調用關系圖、include關系圖等，提高閱讀效率。
通過Run的Show configuration可以查看配置信息：
下面看看對dot的配置：
#--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES MSCGEN_PATH = DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES----------------------------打開dot功能。 DOT_NUM_THREADS = 0 DOT_FONTNAME = Helvetica----------------------設置dot功能的字體和大小。 DOT_FONTSIZE = 10 DOT_FONTPATH = CLASS_GRAPH = YES----------------------------類等關系圖。 COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES UML_LOOK = NO UML_LIMIT_NUM_FIELDS = 10 TEMPLATE_RELATIONS = NO INCLUDE_GRAPH = YES----------------------------include關系圖。 INCLUDED_BY_GRAPH = YES CALL_GRAPH = YES----------------------------調用和被調用關系圖。 CALLER_GRAPH = YES GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png----------------------------dot輸出的圖像格式。 INTERACTIVE_SVG = NO DOT_PATH = /usr/bin/dot-------------------一定要指定的系統中dot路徑。 DOTFILE_DIRS = MSCFILE_DIRS = DIAFILE_DIRS = PLANTUML_JAR_PATH = PLANTUML_INCLUDE_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES DOT_CLEANUP = YES
生成的函數調用關系圖：
include關系圖：
