Ubuntu下doxygen+graphviz使用概錄

關鍵詞：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關係圖：