一、前言
使用
VScode
进行ESP32
编程的时候,发现函数注释,文件注释。这些比较麻烦,作为一个软件工程师,你的代码里面必须有比较重要的注释,所以需要使用一些方法来解决这个问题
二、环境准备
安装
Doxygen Documentation Generator
插件做完第三步,会打开一个
setting.json
的文件
三、setting.json配置
- 把下面文件添加到
setting.json
文件
"doxdocgen.file.fileTemplate": "***************************************\n@file {name}",
"doxdocgen.file.versionTag": "@version 0.1",
"doxdocgen.file.copyrightTag": [
"@copyright Copyright (c) {year}"
],
"doxdocgen.file.customTag": [
// "@note : [详细的修改时间]",
// "@date : [修改时间]",
// "@content : [修改内容]",
//"@author : [Lim]",//作者
"***************************************"
],
"doxdocgen.generic.briefTemplate": "@brief : {text}",
"doxdocgen.generic.authorTag": "@author : {Lim} (emimand1010@gmail.com)",
"doxdocgen.generic.dateTemplate": "@date : {date}",
//"doxdocgen.generic.paramTemplate": "@param : {in/out} - {参数说明} ",
//"doxdocgen.generic.returnTemplate": "@return{indent:8}{type}: ",
"doxdocgen.generic.paramTemplate": "@param : {indent:10}{param} - {参数说明}: ",
"doxdocgen.generic.returnTemplate": "@return : {type} - {函数返回值说明} ",
//"doxdocgen.generic.authorName": "Lim",
"doxdocgen.generic.customTags": [
//"@warning: [特殊属性说明]",
//"@note: [修改详情]",
],
"doxdocgen.file.fileOrder": [
"file", //文件名
"author", //文件介绍
"brief", //作者
"version", //版本
"date", //日期
"copyright", //版权信息
"empty", //空行
"custom" //自定义信息
],
"doxdocgen.generic.order": [
"brief", //函数简介
"empty", //空行
"author", //作者
"tparam", //C++ 参数
"param", //C参数
"return", //返回
"custom" //自定义信息
],
- 一些配置参数介绍
C:Comment PreFix : 表示除了注释第一行和最后一行其他注释行的前缀
**C:First Line:**表示注释第一行显示的内容
**C:Last Line:**表示注释最后一行显示的内容
**C:Trigger Sequence:**设置触发注释的方式,类似于快捷键,输入字符序列然后回车即可自动填充注释信息
**Cpp:Tparam Tempate:**表示函数参数注释
**File:Copyright Tag:**表示填充的版权信息,需要在settings.json中进行配置
**File:File Order :**用于对文件头注释信息排序,即按照规定的顺序对各注释字段排序
**File:File Template:**文件名称注释,@file {name},表示会生成注释行@file name会被文件名称替换
**File:Version Tag:**文件版本信息注释,@version 0.1,则自动生成的文件头注释会有此信息行
**Generic:Author Email:**使用到邮箱信息时,会以此处的邮箱进行自动填充
**Generic:Author Name:**使用到用户名信息时,会以此处的信息进行自动填充
**Generic:Author Tag:**用户名注释行会以此处设置的格式进行填充
**Generic:Brief Template:**表示要填充的说明信息
**Generic:Custom Tags:**表示用户自定义信息,需要在settings.json中配置保存
**Generic:Date Format:**设置要显示的日期格式
**Generic:Date Template:**设置日期注释行,日期格式按上述设置的格式显示
**Generic:Order:**设置函数注释各字段的排列顺序
**Generic: Param Template:**设置函数参数注释行格式,可自动罗列函数参数信息
**Generic: Return Template:**设置函数返回值注释行的格式
四、验证
文件注释
找到
顶格
输入**/****
- 函数注释
这里有有一个小问题,就是如果函数的返回类型是 void
,那么就不会显示 return
字样。
五、格式化文档
本来想去看看 vscode
的代码格式工具,但是查了资料,在 C/C++
这个插件里面集成了格式化 C/C++ 的功能
安装
C/C++
使用
右键鼠标点击文件,点击格式化文档
也可以使用快捷键
Shift+Alt+F
文章是自己总结而记录,有些知识点没说明白的,请各位看官多多提意见,多多交流,欢迎大家留言
如果技术交流可以加以下群,方便沟通
QQ群:370278903
点击链接加入群聊【蜡笔小芯的嵌入式交流群】