在VSCode中使用Doxygen插件注释代码 + Doxygen GUI生成API文档

Doxygen是用来根据代码中注释生成标准API文档的一种方式。

1、在VSCode中使用Doxygen插件注释代码

1.1、在VSCode中安装Doxygen插件

在“扩展”中输入“doxygen”，找到Doxygen Documentation Generator，安装这个插件。

1.2、配置Doxygen插件

1.2.1、进入配置界面

其实安装过这个插件之后，已经可以使用了。
但是我们可以来简单设置下插件，输入一些个性化的信息。
单击该插件右下角齿轮状的配置图标，选择Settings进入配置界面。

1.2.2、配置项的具体设置

可以配置Version Tag版本、Author Email作者邮箱、Author Name作者名字等。

以上一些配置是可以直接在输入框中写的。
还有一些配置需要在settings.json中设置的，比如Copyright Tag版权信息标签、Custom Tag用户自定义标签、File Order文件注释顺序等。

打开settings.json配置文件，如下所示。

可以看到其实刚才在文本框中输入的信息也是自动生成在其中，比如doxdocgen.generic.authorName等。

下图也自定义了一个doxdocgen.file.customTag，用来展示changelog修改日志，包含如何设置一个表格。

后文有生成表格的效果截图

1.3、使用Doxygen插件注释代码

在文件的开头输入/**，回车，会生成关于文件的注释。

在函数上方输入/**，回车，会生成关于函数的注释。

2、使用Doxygen GUI生成文档

2.1、安装Doxygen

下载地址，根据电脑系统选择。

2.2、Doxygen GUI 生成文档

安装完上面的Doxygen后，就会有Doxywizard这个GUI界面的配置软件。
打开后如下图，整个过程大概是这样：首先选择项目路径，然后使用Wizard和Expert来配置，接着切换到Run去运行doxygen生成文档。

Project选项卡，输入项目名称、概述、版本、Logo、源码路径、生成文档路径等。

Mode选项卡，可以配置提取模式和编程语言。
提取模式，指的是从哪里生成文档，默认是Documented entities only指的是仅从已注释的entity实体中提取生成文档。

entity实体：指的是doxygen可以处理的各类编程元素，比如函数、结构体、变量都可以理解为实体；

programming language则是用什么语言就选什么，比如我用C，就选Optimize for C or PHP output

Output选项卡，是配置输出的格式，默认是勾选HTML和LaTeX两个。
根据自己需求，我只选HTML也就可以了。

Diagrams选项卡，配置生成图表的格式。

Expert是一些比较高级的配置选项，就不在这里展开了。

Run选项卡，单击Run doxygen运行Doxygen生成文档，生成后可以使用Show HTML output查看HTML内容。

2.3、生成的HTML文档

最上方是工程名、版本、概述。
右上角是搜索，可以搜索文件、函数、数据结构类型等。
左侧是文档导航。
正文部位为生成的API文档内容了。

在上面setting.json中我们还设置了一个changelog修改日志的表格，效果如下：

3、Doxygen中的文档注释命令

详细说明可以参考官方文档，这里只是抛砖引玉，简单介绍下doxygen中commands这个概念。

其实在上面已经使用了不少的文档注释命令了，就是@开头的。（也可以把@替换成\）

比如，在文档开头注释的@file-当前文件名称、@author-作者、@date-日期等。
比如，在函数注释里提到的@brief-概述、@param-参数说明等。

命令是为了方便使用，比如：

• @author-作者，你的名字通常是不会改变的，所以可以设定为固定的内容。
• @date-日期，日期是更新变化的，使用命令就可以不用每次手动输入。

根据命令的不同，生成出来的文档效果也是不同的，再介绍几个，比如：

• @see可以用来生成链接，可以跳转到其他地方。
• @note是笔记说明，输出文档会有黄色标记。
• @warning是警告，输出文档会有红色标记。
• @bug说明此处有bug，输出文档会有紫色标记。

生成的文档就会有如下图这样的视觉增强的效果: