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关系图：