代码文档管理

文章目录

• • 注释风格
  • • 文件
    • 函数
    • 变量
  • 绘制调用图
  • • 安装 Graphviz
  • 文档生成
  • • 安装 Doxygen
    • 配置
    • 运行

本文简单介绍利用 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;
}

变量

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

/**
 * @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

2. 编辑 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