Ubuntu下的Doxygen+VScode实现C/C++接口文档自动生成
1、 Doxygen简介
Doxygen 是一个由 C++ 编写的、开源的、跨平台的文档生成系统。最初主要用于生成 C++ 库的 API 文档，但目前又添加了对 C、C#、Java、Python、Fortran、PHP 等语言的支持。其从源代码中提取注释，并生成多种输出格式，如HTML、PDF、LaTeX、RTF等，以帮助开发者创建易于阅读和理解的代码文档。
Doxygen 简化了另行编写文档带来的重复性劳动，将代码和文档的工作合二为一。经过 10 年的迭代，Doxygen 成为了 C/C++ 项目首选的文档生成工具。
官网地址：https://www.doxygen.nl/
1、安装Doxygen
1）方法一：
ubuntu下apt命令快速安装
sudo apt-get install doxygen
# sudo apt-get install doxygen-gui
注意，如需在html的文档，中显示类图等关系图，需要安装graphviz库，安装命令如下
sudo apt-get install graphviz
且需要在Doxyfile配置文件中的DOT_PATH指定graphviz的命令行路径
验证查看一下版本：
$ doxygen --version
1.9.1
2）方法二：
采用源码编译，则需要先下载源码，源码下载地址，点这里
执行如下命令
cd doxygen-1.12.0
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=~/DOXYGEN .. # 指定安装doxygen的用户目录为~/DOXYGEN
make
make install
添加到环境变量中
vim .bashrc
export PATH=$HOME/DOXYGEN/bin:$PATH
查看一下安装情况
doxygen --version
2.doxygen注释自动生成插件
1) IDE中安装doxygen注释辅助生成插件
正式标注前，介绍一款VsCode下的doxygen插件Doxygen Documentation Generator
2）配置插件的一些默认参数
首先配置注释提示块的触发快捷方式，默认是/**触发的，打开插件面板，找到Doxygen Documentation 插件，点击配置图标，找到到Extension Settings
修改为如下///，当然，不修改使用默认的/**也是可以的
采用默认的///触发效果，在函数头输入///按下回车后如下：
采用默认的/**触发效果：
此外，还有很更多的默认参数，根据自己的需要进行配置，可以极大的提高效率，避免写注释时，大量的复制粘贴操作，如下可配置默认的作者、邮箱等；
可在配置中，修改如下内容
注意，上面的注释辅助生成插件不是必须的，不同的IDE环境，可能有不同的插件；即使不安装这个，也不影响doxygen的使用，只是需要手动按doxygen的注释语法，逐一手动输入即可；
3. doxygen注释基本语法
/**
* @file main.cpp
* @author your name (you@domain.com)
* @brief
* @version 0.1
* @date 2024-11-24
*
* @copyright Copyright (c) 2024
*
*/
#include <iostream>
/**
* @brief main 函数
*
* @param argc
* @param argv
* @return int
*/
int main(int argc, char** argv)
{
std::cout<< "HelloWorld"<< std::endl;
return 0;
}
/**
* @brief helloworld fun
*
* @param num
* @param str
* @return int
*/
int helloWorld(int num, char* str) {
return 0;
}
/**
* @brief 这个一个Hello -class类
*
*/
class Hello
{
public:
/**
* @brief num变量
*
*/
int num;
/**
* @brief index介绍
*
*/
int index;
/**
* @brief Construct a new Hello object
*
* @param a
* @param b
*/
Hello(int a, int b);
Hello();
~Hello();
};
/**
* @brief Hello2
*
*/
class Hello2: public Hello
{
public:
/**
* @brief Construct a new Hello 2 object
*
* @param a
* @param b
*/
Hello2(int a, int b);
/**
* @brief Destroy the Hello 2 object
*
*/
~Hello2();
};
4. doxygen的生成
首先应生成一个doxygen的配置文件，使用如下命令：
doxygen -g # 默认创建文件名为Doxyfile
# doxygen -g dox-config-file # 指定文件名
通过该配置文件，可以指定生成doxygen文档的输入、输出、生成范围等
以下是一些常用的Doxyfile配置选项：
| 选项 | 说明 |
|---|---|
| INPUT | 指定要生成文档的源代码目录 |
| RECURSIVE | 是否递归搜索子目录，设置为YES可以让Doxygen递归地搜索所有的源代码文件 |
| FILE_PATTERNS | 源文件匹配 |
| EXCLUDE | 不希望处理的文件 |
| OUTPUT_DIRECTORY | 指定生成的文档的输出目录 |
| PROJECT_NAME | 指定生成文档的工程名 |
| OUTPUT_LANGUAGE | 指定输出文档的语言 |
| GENERATE_HTML | 是否生成HTML报告 |
| GENERATE_LATEX | 是否生成LATEX报告，如果不需要生成LaTeX文档，可以设置为NO |
| EXTRACT_PRIVATE | 是否解析类的私有变量 |
| CLASS_DIAGRAMS | 是否生成类图 |
| STRIP_FROM_PATH | 指定文件剥离路径 |
| DOT_PATH | Graphviz命令路径(如/usr/bin/dot) |
| HAVE_DOT | 开启类图 |
| CALL_GRAPH | 调用图 |
| CLASS_DIAGRAMS | 继承图 |
| COLLABORATION_GRAPH | 协作图 |
| INCLUDE_GRAPH | 包含图 |
| GRAPHICAL_HIERARCHY & DIRECTORY_GRAPH | 依赖图 |
| HAVE_DOT & DOT_GRAPH | 成员关系 |
| NAMESPACE_GRAPH | 命名空间 |
| ENABLED_SECTIONS | 全局变量 |
执行生成命令，生成文档
# 指定默认配置文件Doxfile，生成文档
doxygen Doxyfile
默认情况下，将生成两类文档html、latex
如无需要latex可在Doxyfile配置文档中配置GENERATE_LATEX = NO后，如下所示
完成！
