Vscode函数注释、文件注释格式化文档

一、前言

使用 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

---

文章是自己总结而记录，有些知识点没说明白的，请各位看官多多提意见，多多交流，欢迎大家留言
如果技术交流可以加以下群，方便沟通