Doxygen + Graphviz 代码自动化分析

Doxygen + Graphviz 代码自动化分析

目录

• 1. 实际需求
• 2. 工具简介
• 3. 使用说明
• 4. 代码注释规范
• 5. 参考

1. 实际需求

• 在开发程序时，需要编写对应的说明文档。

• 在阅读现有的项目源代码时，需要梳理函数间的调用关系。

使用 doxygen工具可以自动地根据代码中的注释生成说明文档，而且还能分析每个文件的调用关系、每个类的继承关系、每个函数的调用关系、每个文件夹的包含关系……而graphviz 工具则可以将这些关系以图形的方式进行展示。

2. 工具简介

doxygen是一种从标记过的C++源代码生成文档的标准工具，也支持C，Objective-C，C#，PHP，Java，Python，IDL，Fortran，VHDL，Tcl等。

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.

graphviz是一种开源的将结构化信息展示成抽象图和网络的工具，用于网络，生物信息，软件工程，数据库和网站设计，机器学习以及其他技术领域的可视性接口。

Graphviz is open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. It has important applications in networking, bioinformatics, software engineering, database and web design, machine learning, and in visual interfaces for other technical domains.

doxygen和graphviz都支持windows、Linux和Mac平台，在Linux中安装时十分简单，

sudo apt install doxygen doxygen-gui 
sudo apt install graphviz

3. 使用说明

Doxywizard是配置和运行doxygen的GUI前端，可以快捷的创建配置文件。

在终端中输入doxywizard命令启动该程序，如下图

（1）设置Step1 和 Step2 中的Wizard 选项卡

• 在Step1中选择doxygen的工作目录

• 设置 doxygen 的项目名称

• 选择待分析的源码文件或目录，可以是单个源码文件，也可以是源码目录

• 选择Scan recursively则递归分析源代码目录中的子目录内的源代码。

• 设置生成文档的输出路径

（2）设置Wizard的其它topics

在Mode中可以设置为指定语言进行优化。

在output中设置要输出哪些文档，一般默认即可（最主要的是生成的html文件）。

在diagrams中选择要生成的图。

（2）设置Expert选项卡

取消勾选FULL_PATH_NAMES，否则生成的文档中，每个文件名前面会带上完整的路径

（3）设置Expert的Build topic

（4）在Input topic中可以设置要排除的文件或目录

（5）设置Dot topic，DOT_PATH中选择graphviz的安装路径，Linux中的默认安装路径

为/usr/bin

到这里就完成了基本的配置，可以将其保存为一个配置文件，下次运行时可以直接调用。

（5）在Run选项卡中点击Run doxygen开始分析源代码，完成后点击show HTML output

会自动打开生成的文档网页。

例如，对于以下示例代码

/**
 * @file main.cpp demo for code file extraction using doxygen
 * @version 1.0
 * @date 2022-06-05
 * @author Simon
 */
#include <iostream>

#define PI 3.141421  /*!< pi */

/**
 * @brief print hello world
 */
void printHello();

/**
 * @brief conversion between degree and radian
 * @param thea : the angle to be converted
 * @param type : 0-degree to radian, 1-radian to degree
 * @return converted theta
 */
double degreeRadian(double theta, int type);

int main() {
    printHello();

    int x = 1, y = 2;
    std::cout << "1 degree = " << degreeRadian(1, 0) << "radian" << std::endl;
    std::cout << "1 radian = " << degreeRadian(1, 1) << "degree" << std::endl;

    return 0;
}

void printHello(){
    std::cout << "Hello, doxygen!" << std::endl;
}

double degreeRadian(double theta, int type){
    printHello();

    if(type == 0)
        return theta / 180 * PI;
    else
        return theta / PI * 180;
}

生成的文档如下图所示

在项目文件下会生成一个html文件夹，每个文件都会对应生成一个html文件，files.html文件为主页（打开的网页就是这个），会链接到各个子html文件。

/mnt/d/doxygen/demo
├─html 
│  └─search
└─latex

4. 代码注释规范

只有按照doxygen的代码注释规范进行注释，才能正确提取代码中的注释，并显示在html文件中。

（1）与代码同行的注释类型：

/*!< ... 批注 ... */
/**< ... 批注 ... */ （推荐）
//!< ... 批注 ...
///< ... 批注 ...  （推荐）

（2）在代码上方的注释类型：

/*!
 * ... text ...
 */

/**
 * ... txt ...
 */

（3）其它不想被包含到文档里的注释：

// ... text ...

/*  ... text ... */

（4）一种常用的注释格规范（一般放在函数、对象、结构体的定义前面）：

/**
 * @brief 表示具体描述说明
 * @param 表示参数说明，有@param、@param[in]和@param[out]三种写法，字面意思
 * @return 表示返回参数
 * @see 表示另见See also，多用在存在继承关系上，\n
   比如A继承了B，但是A没有重写继承来的方法C，在C上就可以注释另见B
*/

（5）对于某个变量或者结构体成员或者类属性的单行注释

int var;  /**< ... 批注 ... */

5. 参考

1. 使用doxygen和graphviz来产生源代码函数调用图

2. 文档生成神器—doxygen的使用和代码注释规范

3. Doxygen 注释语法和使用