关键词：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: 读取成功。 -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 ",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关系图：
