代码文档管理

本文简单介绍利用 Doxygen + Graphviz 制作代码文档

注释风格

VSCode 为例,安装 Doxygen Documentation Generator 插件

后续只要在文件开头、函数上方等位置键入"/**",然后回车,即可生成响应的注释格式。

文件

文件的注释风格举例:

/**
 * @file init.c
 * @author Wang Yu (ywang_wnlo@hust.edu.cn)
 * @brief data structure and initialize functions
 * @version 0.1
 * @date 2019-07-25
 * 
 * @copyright Copyright (c) 2019 HUST WNLO NVMRG. All rights reserved
 * 
 */

文件引用

函数

函数的注释风格举例:

/**
 * @brief main function of the simulator
 * 
 * @param argc: args count
 * @param argv: args vector
 * @return int: return value
 */
int main(int argc, char const *argv[])
{
	return 0;
}

函数调用1
函数调用2

变量

结构体变量的注释风格举例:

/**
 * @brief ssd info and global variable
 * 
 */
struct ssd_info
{
	struct parameter_info *parameter;			/**< SSD parameter */
	struct channel_info *channel;				/**< channels info in this ssd */
}

结构体变量

绘制调用图

好的文档离不开程序调用图,本文选择利用 Linux 系统上的 Graphviz 来绘制函数之间的调用图,以及文档直接依赖,结构体依赖等。

安装 Graphviz

在 Linux 系统中安装 Graphviz 包即可。以下均以 Ubuntu 为例。

sudo apt install graphviz

文档生成

利用 Doxygen 分析代码结构,并生成文档。

安装 Doxygen

sudo apt install doxygen

配置

  1. 生成配置文件,默认文件名为 Doxygen
doxygen -g
  1. 编辑 Doxygen 配置文件
PROJECT_NAME = "项目名称"
PROJECT_NUMBER = "版本号"
OUTPUT_DIRECTORY = 输出目录(最好相对位置)
OUTPUT_LANGUAGE = 输出语言

# 支持 C, C++, JAVA, FORTRAN, VHDL, SLICE
OPTIMIZE_OUTPUT_FOR_C  = YES

EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES

# 分析 .c 和 .h 文件
FILE_PATTERNS = *.c \
                *.h

GENERATE_TREEVIEW = YES

# 表示利用 graphviz 画图
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES

运行

doxygen Doxygen
posted @ 2022-04-06 23:54  ywang_wnlo  阅读(94)  评论(0编辑  收藏  举报