日常开发除了编写优良的代码，同样需要写好可读的注释。但对于开发人员而言，要写好注释，也是一件挺繁琐的事，尤其是那类注释基本都是固定的格式，如源文件开头部分的声明，还有函数声明等。
而 doxygen 工具正好可以帮助生成固定的注释模板，可以少敲很多内容，极大的提高开发人员写注释的效率，下面以 vscode 为例进行安装使用说明。
一、vscode 安装 doxygen 插件
直接在插件商店搜索 Doxygen Documentation Generator 进行安装，安装完成后，打开用户配置（F1->Open Settings），增加如下配置：
// File copyright documentation tag. Array of strings will be converted to one line per element. Can template {year}.
"doxdocgen.file.copyrightTag": [
"@copyright Copyright (c) {year}"
],
// Additional file documentation. Array of strings will be converted to one line per element. Can template {year}, {date}, {author}, and {email}.
"doxdocgen.file.customTag": [],
// The order to use for the file comment. Values can be used multiple times. Valid values are shown in default setting.
"doxdocgen.file.fileOrder": [
"file",
"author",
"brief",
"version",
"date",
"empty",
"copyright",
"empty",
"custom"
],
// The template for the file parameter in Doxygen.
"doxdocgen.file.fileTemplate": "@file {name}",
// Version number for the file.
"doxdocgen.file.versionTag": "@version 0.1",
// Set the e-mail address of the author. Replaces {email}.
"doxdocgen.generic.authorEmail": "[email protected]",
// Set the name of the author. Replaces {author}.
"doxdocgen.generic.authorName": "your name",
// Set the style of the author tag and your name. Can template {author} and {email}.
"doxdocgen.generic.authorTag": "@author {author} ({email})",
// The template of the brief Doxygen line that is generated. If empty it won't get generated at all.
"doxdocgen.generic.briefTemplate": "@brief {text}",
// The format to use for the date.
"doxdocgen.generic.dateFormat": "YYYY-MM-DD",
// The template for the date parameter in Doxygen.
"doxdocgen.generic.dateTemplate": "@date {date}",
// The order to use for the comment generation. Values can be used multiple times. Valid values are shown in default setting.
"doxdocgen.generic.order": [
"brief",
"empty",
"tparam",
"param",
"return",
"custom"
],
// Custom tags to be added to the generic order. One tag per line will be added. You have to specify the prefix yourself.
"doxdocgen.generic.customTags": [],
// The template of the param Doxygen line(s) that are generated. If empty it won't get generated at all.
"doxdocgen.generic.paramTemplate": "@param {param} ",
// The template of the return Doxygen line that is generated. If empty it won't get generated at all.
"doxdocgen.generic.returnTemplate": "@return {type} ",
// Decide if the values put into {name} should be split according to their casing.
"doxdocgen.generic.splitCasingSmartText": true,
设置好后，在源码文件头输入 “/**” ，然后按回车，就可以看到如下自动生成的文件头注释了
在函数上面同样输入“/**”，然后按回车，可以看到如下自动生成的函数注释
二、使用 doxygen 命令生成注释文档
使用 doxygen 的另一个好处是可以通过 doxygen 命令工具针对符合 doxygen 格式的注释生成文档直接进行查看。
在 MAC 下直接使用如下命令进行安装：
brew install doxygen
安装完成后，在对应的代码目录下，执行如下命令先生成配置文件 Doxyfile
doxygen -g
然后针对默认生成的配置文件对一些配置项进行修改，下面列举说明了可能常用的配置项
| 配置项 | 说明 |
|---|---|
| PROJECT_NAME | 项目名称 |
| PROJECT_NUMBER | 文档版本号 |
| EXTRACT_ALL | 默认NO，设置成YES，则解析所有代码，即使没有对应的注释 |
| EXTRACT_PRIVATE | 默认NO，设置成YES，则解析私有项 |
| EXTRACT_STATIC | 默认NO，设置成YES，则解析静态项 |
| INPUT | 指定需要解析的目录，以空格隔开 |
| FILE_PATTERNS | 针对INPUT中的目录再具体匹配的文件，如*.h |
| RECURSIVE | 递归检索文件 |
| EXCLUDE | 排除指定目录不被解析 |
| EXCLUDE_PATTERNS | 针对EXCLUDE中的目录指定排除的文件，如/.git/ |
| HAVE_DOT | 使用dot工具进行绘图，需要安装Graphviz |
| CALL_GRAPH、CALLER_GRAPH | 绘制调用关系，需要先将HAVE_DOT置成YES |
| OPTIMIZE_OUTPUT_FOR_C | 如果针对的是C代码，可以指定为YES |
| HIDE_SCOPE_NAMES | C 语言不存在域名空间，可以设置为YES |
| TYPEDEF_HIDES_STRUCT | 按照 typedef 定义的类型名进行文档化 |
| GENERATE_LATEX | 不生成latex格式文档，置YES |
| GENERATE_TREEVIEW | 生成侧边栏 |
| GENERATE_HTMLHELP | 生成 .chm 格式文件 |
| REFERENCED_BY_RELATION、REFERENCES_RELATION、REFERENCES_LINK_SOURCE | 显示的函数相互调用关系 |
修改完成之后，直接再执行命令 doxygen 即可，然后打开 html 目录下的 index.html 文件就可查看接口说明文档。
