vscode 生成标准化注释
简介
Doxygen是一款非常好用的代码文档工具，在大部分情况下，你只需要在写代码的时候顺便按照指定格式写上一些注释，随后使用doxygen就能自动帮你生成一套文档。本文将简单讲解如何使用vscode 便捷的生成标准化注释。
本文章暂时不过多介绍注释格式,重点介绍工具怎么使用
环境准备
- vscode 及插件 Doxygen Documentation Generator - With Parameter Directio
相关资料
- 官网 https://www.doxygen.nl/download.html Doxygen工具用于生成标准化文档
- 教程http://blog.sysu.tech/Tools/Doxygen%E5%85%A5%E9%97%A8%E6%8C%87%E5%8C%97/
Doxygen Documentation
注释文件头与函数名
插件安装与设置
-
vscode 在线安装
并进入设置可以不关系版本关系，直接使用
-
vscode 使用离线安装VSIX
进入下载地址https://marketplace.visualstudio.com/items?itemName=zatkins-dev.doxdocgen-with-direction
根据提示安装对应VScode版本的安装包，放到离线电脑安装
-
配置Doxygen插件
进入vscode设置，可以看到配置分为3个用户 工作区 文件夹，三者区别
- 用户: 支持配置同步，全局可以用存储在C:\...\AppData\Roaming\Code\User\settings.json
- 工作区: 当前工作区下生效，配置文件存在工作区文件中XXX.code-workspace
- 文件夹: 指定文件夹下生效，配置存储在**.vscode**
如果配置到文件夹/工作区下，可以将配置.vscode打包给别人来保证配置的一致性
-
注释风格
现在我们先根据写好的配置文件
.vscode/settings.json来学习了解自定义，您还可以将这个配置文件直接放入工作文件夹中，在.vscode所在文件夹，用vscode打开即可自动调用此配置此配置文件大部分由vscode自动生成
{ "C_Cpp.doxygen.generatedStyle": "/**", "doxdocgen.file.copyrightTag": [ "@copyright{indent:14}Copyright (c) {year} Gltech" ], "doxdocgen.file.customTag": [ "@htmlonly", "<span style=\"font-weight: bold\">History</span>", "@endhtmlonly ", "Version|Auther|Date|Describe", "------|----|------|-------- ", "1.0|{author}|{date}|Create File", ], "doxdocgen.file.versionTag": "@version {indent:14}0.1", "doxdocgen.file.fileTemplate": "@file {indent:14}{name}", "doxdocgen.generic.authorTag": "@author{indent:14}{author} ({email})", "doxdocgen.generic.briefTemplate": "@brief{indent:14}{text}", "doxdocgen.generic.dateTemplate": "@date{indent:14}{date}", "doxdocgen.generic.paramTemplate": "@param {param} {indent:14}", "doxdocgen.file.fileOrder": [ "file", // @file "brief", // @brief 简介 "author", // 作者 "version", // 版本 "date", // 日期 "copyright", // 版权 "empty", "custom" // 自定义 ], "doxdocgen.generic.order": [ "brief", "param", "empty", "return", ], "doxdocgen.generic.authorEmail": "chengmeng_2@outlook.com", "doxdocgen.generic.authorName": "mengplus", "doxdocgen.generic.commandSuggestionAddPrefix": false, }copyrightTag: 版本标签 {version}
**{indent:14}:**对齐到14字节
**customTag:**文件用户自定义标签{custom}
**versionTag:**版本标签
**fileTemplate:**文件标签{file}
**authorTag:**作者标签{Tag}
briefTemplate简要模板{brief}
dateTemplate日期模板
paramTemplate参数模板
**fileOrder:**文件注释排序，在文件第一行调用自动按照这个模板输出
generic.order通用的排序
authorName作者名称{author}
authorEmail作者参数{email}
根据上文提供的配置可以得到如下的配置效果
/** * @file module_XXXX.h * @brief * @author mengplus (chengmeng_2@outlook.com) * @version 0.1 * @date 2025-02-12 * @copyright Copyright (c) 2025 * * @htmlonly * <span style="font-weight: bold">History</span> * @endhtmlonly * Version|Auther|Date|Describe * ------|----|------|-------- * 1.0|mengplus|2025-02-12|Create File */
插件的触发条件
在默认配置参数triggerSequence可以获知 在代码开头或者函数之上输入/**回车即可
"doxdocgen.c.triggerSequence": "/**"
操作演示
代码片段
变量注释 自定义片段快捷插入代码中
vscode设置->代码片段->C.json
同样全局的配置放置在C:\...\AppData\Roaming\Code\User\snippets\cpp.json
同样配置也是json格式,如下示例
{ "Print to console": { //片段名称
"prefix": "log",//触发条件
"body": [//片段内容
"console.log('$1');",//$1 tab第一个焦点
"$2"//$2 tab第二个焦点
],
"description": "Log output to console"//片段的描述
},
}
输入触发词后 回车确认输入片段
了解基本使用方式后，我们就可以使用这个功能实现更加丰富的代码注释,请将下文放入c.json与cpp.json中
由于c/cpp经常混编
{
"header init": {
"prefix": "#ifndef",
"body": [
"#ifndef __$1_H_ \r\n#define __$1_H_\r\n$0\r\n#endif",
],
"description": "头文件初始化"
},
"兼容C": {
"prefix": "#ifdef ",
"body": [
"#ifdef __cplusplus",
"extern \"C\"",
"{",
"#endif",
"$1",
"#ifdef __cplusplus",
"}",
"#endif"
],
"description": "兼容C声明文件"
},
"变量说明": {
"prefix": "/*! ",
"body": [
" /*!< $1 */",
],
"description": "变量说明"
}
}
触发代码片段
现在愉快的使用vscode编写代码吧