配置

安装和快速上手

快速查阅功能

配置字段，一个json文件，列出了所有字段和简单的功能介绍。

自动更新最后编辑时间、编辑人、文件路径：

要开启这个功能，需要在首选项设置中填写对应的属性：

  "fileheader.customMade": {
    "Date": "Do not edit", // 文件创建时间(不变)
    // 文件最后编辑者
    "LastEditors": "git config user.name && git config user.email", 
    "LastEditTime": "Do not edit", // 文件最后编辑时间
    "FilePath": "Do not edit" // 文件在项目中的相对路径 自动更新
  }
  // 不填写对应属性即关闭对应功能

图案注释

一键生成佛祖保佑永无BUG、神兽护体等注释图案

/*
 * ......................................&&.........................
 * ....................................&&&..........................
 * .................................&&&&............................
 * ...............................&&&&..............................
 * .............................&&&&&&..............................
 * ...........................&&&&&&....&&&..&&&&&&&&&&&&&&&........
 * ..................&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&..............
 * ................&...&&&&&&&&&&&&&&&&&&&&&&&&&&&&.................
 * .......................&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&.........
 * ...................&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&...............
 * ..................&&&   &&&&&&&&&&&&&&&&&&&&&&&&&&&&&............
 * ...............&&&&&@  &&&&&&&&&&..&&&&&&&&&&&&&&&&&&&...........
 * ..............&&&&&&&&&&&&&&&.&&....&&&&&&&&&&&&&..&&&&&.........
 * ..........&&&&&&&&&&&&&&&&&&...&.....&&&&&&&&&&&&&...&&&&........
 * ........&&&&&&&&&&&&&&&&&&&.........&&&&&&&&&&&&&&&....&&&.......
 * .......&&&&&&&&.....................&&&&&&&&&&&&&&&&.....&&......
 * ........&&&&&.....................&&&&&&&&&&&&&&&&&&.............
 * ..........&...................&&&&&&&&&&&&&&&&&&&&&&&............
 * ................&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&............
 * ..................&&&&&&&&&&&&&&&&&&&&&&&&&&&&..&&&&&............
 * ..............&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&....&&&&&............
 * ...........&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&......&&&&............
 * .........&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&.........&&&&............
 * .......&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&...........&&&&............
 * ......&&&&&&&&&&&&&&&&&&&...&&&&&&...............&&&.............
 * .....&&&&&&&&&&&&&&&&............................&&..............
 * ....&&&&&&&&&&&&&&&.................&&...........................
 * ...&&&&&&&&&&&&&&&.....................&&&&......................
 * ...&&&&&&&&&&.&&&........................&&&&&...................
 * ..&&&&&&&&&&&..&&..........................&&&&&&&...............
 * ..&&&&&&&&&&&&...&............&&&.....&&&&...&&&&&&&.............
 * ..&&&&&&&&&&&&&.................&&&.....&&&&&&&&&&&&&&...........
 * ..&&&&&&&&&&&&&&&&..............&&&&&&&&&&&&&&&&&&&&&&&&.........
 * ..&&.&&&&&&&&&&&&&&&&&.........&&&&&&&&&&&&&&&&&&&&&&&&&&&.......
 * ...&&..&&&&&&&&&&&&.........&&&&&&&&&&&&&&&&...&&&&&&&&&&&&......
 * ....&..&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&...........&&&&&&&&.....
 * .......&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&&..............&&&&&&&....
 * .......&&&&&.&&&&&&&&&&&&&&&&&&..&&&&&&&&...&..........&&&&&&....
 * ........&&&.....&&&&&&&&&&&&&.....&&&&&&&&&&...........&..&&&&...
 * .......&&&........&&&.&&&&&&&&&.....&&&&&.................&&&&...
 * .......&&&...............&&&&&&&.......&&&&&&&&............&&&...
 * ........&&...................&&&&&&.........................&&&..
 * .........&.....................&&&&........................&&....
 * ...............................&&&.......................&&......
 * ................................&&......................&&.......
 * .................................&&..............................
 * ..................................&..............................
 */

插件配置

参考模板设置的方式，找到配置项"fileheader.configObj",修改这个对象即可。

整体功能

所有的功能都在配置字段里面有简单的描述，可以先看一下整体的配置功能，然后再本文档中搜索对应的字段了解详细用法。

配置：

1. 自定义语言注释符号(可选项)：

用户自定义注释符号

language自定义注释形式须知：

此项配置是最高级别的，会覆盖插件的语言注释格式
任何语言/文件(新的语言、特殊的文件)，用户都可以设置对应的注释符号，只要像上述栗子中的格式一样即可。
还有一种场景：像issue中提到的，某些库会对注释格式有特殊要求，库会对其识别、处理。插件标准的注释格式并不能满足需求，此时在config.language里添加一项配置即可。

此项配置的意义是：

以防以后项目不维护了，出现新的流行语言，注释形式也不一样了。用户也可以自定以注释的符号.

看到这里，我如此用心良苦，真的不点右上角赏我一个Star⭐️吗？

language设置：

// 设置
"fileheader.configObj": {
    "language": {
        // 普通后缀文件
        "tsx": {
            "head": "/$$",
            "middle": " $ @",
            "end": " $/",
            "functionParams": "typescript", // 使用ts语言解析函数参数
            // 函数自定义注释符号：如果有此配置 会默认使用
            "functionSymbol": {
              "head": "/******* ", // 统一增加几个*号
              "middle": " * @",
              "end": " */"
            }
        },
       // 一次匹配多种文件后缀文件 不用重复设置
       "h/hpp/cpp": {
          "head": "/*** ", // 统一增加几个*号
          "middle": " * @",
          "end": " */"
        },
        // 针对有特殊要求的文件如：test.blade.php
        "blade.php":{
          "head": "<!--",
          "middle": " * @",
          "end": "-->",
        }
    },
}

language下面的属性可以是文件后缀，也可以是语言类型，比如test.js,js是文件后缀,javascript是语言类型.
推荐使用文件后缀来设置,这样比较不容易出错。

上述设置的注释结果：

test.java文件生成的注释：

/$$
 $ @Author: OBKoro1
 $ @Date: 2019-01-19
 $ @LastEditors: OBKoro1
 $ @LastEditTime: 2019-01-19
 $ @Description: 头部注释
 $ @FilePath:  /itemName/src/index.js // 自动生成文件路径，在配置中搜索FilePath
 $/
/$$
 $ @description: 函数注释
 $ @param {type} 
 $ @return: 
 $/

一次匹配多种文件后缀文件

/***
 * Author       : OBKoro1
 * Date         : 2019-05-13 15:54:32
 * LastEditors  : OBKoro1
 * LastEditTime : 2020-02-14 22:04:52
 * FilePath     : /fileHead/test.h
 * Description  : c++的h、hpp、cpp文件都使用一样的注释
 * https://github.com/OBKoro1
 **/

有特殊要求的文件注释：

上面配置中的blade.php，只会覆盖以blade.php为后缀的文件，不会影响到php后缀的文件。 有些库会对一些文件有特殊的要求，导致注释也需要跟着改变，如该issue中所描述的test.blade.php和test.php里面是两种内容。注释配套的：在注释之前/之后添加内容、指定行数前添加注释

test.blade.php生成的注释：

<!--
 * @Author: OBKoro1
 * @Date: 2019-10-20 16:37:49
 * @LastEditors: OBKoro1
 * @LastEditTime: 2019-10-20 16:49:09
 * @FilePath: /xpdevtool/src/test.blade.php // 自动生成文件路径，在配置中搜索FilePath
 * @Description: 描述
-->

默认注释形式：

"fileheader.configObj": {
    "annotationStr": {
        "head": "/*", // 自定义注释头部
        "middle": " * @", // 自定义注释中间部分(注意空格,这也是最终生成注释的一部分)
        "end": " */", // 自定义注释尾部
        "use": false // 是否使用自定义注释符号
    }
}

这个配置是默认配置，如果使用的话(use:true)，生成的注释为：

/*
 * @Author: OBKoro1
 * @Github: https://github.com/OBKoro1
 * @Date: 2018-12-12 18:50:10
 * @LastEditors: OBKoro1
 * @LastEditTime: 2018-12-13 15:54:05
 * @Description: 头部注释
 */
/*
 * @description: 
 * @param {type} 
 * @return: 函数注释
 */

annotationStr配置规则：

匹配config.language(用户设置的自定义符号)1
匹配插件支持的语言
当上面两种注释形式都没匹配到时，并且use选项为true，才会使用此项配置。

2. 自动添加文件头部注释:

该选项为了那些(比如我自己)，老是忘记添加文件头部注释的同学而添加的,配合下方的头部注释黑名单使用更佳，妈妈再也不用担心我忘记添加头部注释了！

"fileheader.configObj": {
  "autoAdd": true, // 默认开启
}

配置规则：

开启该选项之后，插件会检测当前保存的文件有没有头部注释，如果没有的话，将为自动添加头部注释(就像你按了头部注释的快捷键一样)。

检测文件没有头部注释的规则:

前15行没有进入该语言/自定义的注释
进入注释之后，注释中没有LastEditors、LastEditTime、FilePath、Date这四个特殊字段
如果使用了自定义特殊字段，那么插件将改为检测自定义的特殊字段。

也就是说你注释模板中没有这四个字段，那就不要开启这项功能，因为会无限添加头部注释(一直检测不到头部文件注释，一直自动添加)。

在本插件中，这四个设置都有其自己的功能，所以以这四个字段为检测标准

满足上述两个条件，插件将视该文件没有头部注释，将在保存文件时自动为其添加头部注释。

autoAlready:只让支持的语言，自动添加头部注释

autoAlready: 自动添加头部注释：只允许插件支持的语言，以及用户通过language 选项自定义的注释。

"fileheader.configObj": {
  "autoAdd": true, // 自动添加头部注释开启才能自动添加
  "autoAlready": true, // 默认开启
}

为什么增加这项配置？

像.json文件这种类型的文件，文件不能添加注释
有一些语言，插件没有支持，添加默认注释，并不适配，导致问题。 (可以通过language选项添加自定义注释来解决。)

将autoAlready关闭，即给所有文件自动添加头部注释，选择权在你们手上。

自动添加文件头部注释限制

自动添加头部注释文件白名单

"fileheader.configObj": {
    "supportAutoLanguage": [ ] // 设置过后只有该数组里面的文件 才会自动添加头部注释
}

规则与黑名单prohibitAutoAdd相同，该功能是为了防止语言实在太多，黑名单设置不过来，提供仅支持特定的几种特定语言的自动添加。

自动添加头部注释黑名单

"fileheader.configObj": {
    "prohibitAutoAdd": [ "json", "md" ] // 禁止.json .md文件，自动添加头部注释
}

插件黑名单的参数接收的是文件后缀，当文件后缀匹配跟黑名单数组内的元素匹配时，该文件不会自动添加头部注释。

自动添加头部注释，本身是一个相当不错的功能，但因为有些文件不适合自动添加注释，比如.json文件是不能有注释的，在这些不适宜的情景下，自动添加会被关闭。

很多人在关闭之后，就会忘记再打开了，这个功能可以很好的解决这个问题，有了这个功能，相信各位以后的注释习惯会越来越好。

自动添加头部注释项目黑名单

场景: 某些项目没有推广头部注释，然后leader/团队成员反感这种行为时，使用该功能。

"fileheader.configObj": {
    "prohibitItemAutoAdd": [ "test_koro", "test_koro2" ] // 禁止test_kro/test_koro2项目自动添加头部注释
}

要禁止项目的全称, 整个项目禁止自动添加头部注释, 可以使用快捷键自行添加头部注释。
如test_koro项目, 需要以test_koro为根目录打开项目，才可以禁止自动添加，如果将其包含，或者打开该项目的一部分则不会被禁止
电脑中如果有其他项目也是完全一样的项目名，那么以该项目为根目录时，也会被禁止自动添加头部注释。（这种场景比较少见）

文件超过一定行数不再自动添加头部注释

"fileheader.configObj": {
    "autoAddLine": 100 // 默认文件超过100行就不再自动添加头部注释
}

文件夹或文件名禁止自动添加头部注释

插件会对地址进行切割，如果完全匹配到文件夹或者文件名字符串则禁止添加。

"fileheader.configObj": {
  "folderBlacklist": [
    "node_modules",
    "文件夹或文件名禁止自动添加头部注释",
    // "webpack.config.js" // 可以禁止某些文件自动添加注释
  ]
}

只允许文件自动添加头部注释一次：

如果某个文件曾经自动添加过头部注释，那么插件会记录该文件的路径，在这次VsCode编辑器关闭前，都将不再允许该文件自动添加头部注释。

有时候我们并不希望该文件自动添加头部注释，删除也没有用，它会一直手动添加，该功能就是为了用于防止这种情况的。

FilePath:文件相对于项目的路径

"fileheader.customMade": {
  "LastEditors": "git config user.name && git config user.email",
  "Date": "Do not edit",
  "LastEditors": "git config user.name && git config user.email",
  "LastEditTime": "Do not edit",
  "FilePath": "Do not edit" // 增加此项配置即可
}

FilePath在4.6.0+将会自动更新，防止因为文件被移动、重命名导致文件路径错误。
将FilePath设为no item name可以去掉项目名称。
将FilePath设为only file name可以去掉路径，只展示文件名。
将FilePath设为only file name without ext可以去掉路径，去掉文件后缀，只展示文件名。
如果想给字段换一个名字，可以在specialOptions中修改它。
字段的值为：生成头部注释时，文件相对于当前VsCode窗口打开的文件夹的路径(如下所示)。
该配置的作用在于：项目的文件夹层级较为复杂或者项目中存在大量相同的文件名(比如一大堆index.js)

比如：

/*
 * Author: OBKoro1 [email protected]
 * Date: 2019-10-20 15:43:37
 * LastEditors: OBKoro1 [email protected] 
 * LastEditTime: 2019-10-20 17:37:45
 * FilePath: /文件夹名称/src/index.js // 默认带上项目名称
 * FilePath: /src/index.js  // "FilePath": "no item name" 去掉项目名称
 * FilePath: index.js  // "FilePath": "only file name" 只剩文件名
 * FilePath: index  // "FilePath": "only file name without ext" 去掉路径，去掉文件后缀，只展示文件名
 */

filePathColon: 修改路径分隔符

配置示例：

"fileheader.configObj": {
   "filePathColon": "\\\\" // \ 路径要转义 所以要写两遍
}

old: FilePath: /文件夹名称/test.js
now: FilePath: \\文件夹名称\\test.js

Author和LastEditors获取git config配置

Author文件创建者和LastEditors文件最后编辑人这连个字段在头部模板支持读取当前项目下的git config配置。

如果想更改这两个字段名可以在specialOptions配置项中更改特殊属性。

使用场景: 在公司项目和个人项目的文件夹下，配置了不同的用户名和邮箱, 在不同作用域内读取不同的git config配置，避免重复设置工作区的烦恼。

PS: 配置详情搜索: gitconfig includeIf，比如文章

目前支持三个值:

同时获取用户名与邮箱: "Author": "git config user.name && git config user.email"
仅获取用户名: "Author": "git config user.name"
仅获取邮箱: "Author": "git config user.email"

版权声明也支持读取git config配置

同时获取用户名与邮箱${git_name_email}: "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_name_email}, All Rights Reserved. "
获取用户名${git_name}: "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_name}, All Rights Reserved. "
获取邮箱${git_email}: "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_email}, All Rights Reserved. "
组合使用: "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_name} email: ${git_email}, All Rights Reserved."

// 头部注释
"fileheader.customMade": {
    // Author字段是文件的创建者 
    "Author": "git config user.name && git config user.email", // 同时获取用户名与邮箱
    // "Author": "git config user.name", // 仅获取用户名
    // "Author": "git config user.email", // 仅获取邮箱
    // "Author": "OBKoro1", // 写死的固定值 不从git config中获取
    "Date": "Do not edit", 
    "LastEditors": "git config user.name && git config user.email",     "LastEditTime": "Do not edit",
    "FilePath": "Do not edit",
    "Description": "",
    // 版权声明 保留文件所有权利 自动替换年份 获取git配置的用户名和邮箱
    // 版权声明获取git配置, 与Author字段一致: ${git_name_email} ${git_name} ${git_email}
    "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_name} email: ${git_email}, All Rights Reserved."
    // "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by 写死的公司名/用户名, All Rights Reserved. "
},

结果:

// "Author": "git config user.name && git config user.email"
// "LastEditors": "git config user.name"
//  "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_name} email: ${git_email}, All Rights Reserved. "
/*
 * Author       : OBKoro1 [email protected]
 * Date         : 2022-05-01 15:35:12
 * LastEditors  : OBKoro1
 * LastEditTime : 2022-05-02 11:31:09
 * FilePath     : /fileHead/function-params/test.js
 * Description  : 
 * Copyright (c) 2022 by OBKoro1 email: [email protected], All Rights Reserved. 
 */

头部注释等宽设置`wideSame`

"fileheader.configObj": {
   "wideSame": false, // 设置为true开启
   "wideNum": 13 // 字段长度 默认为13
}

开启效果：

wideNum为13长度充足，每个字段都有空格:

/*
 * Author       : OBKoro1
 * Date         : 2019-09-24 20:25:33
 * LastEditors  : OBKoro1
 * LastEditTime : 2019-12-16 21:16:08
 * FilePath     : /fileHead/test.js
 */

之前没有对齐的注释插件也会更新它的修改时间, 效果如下

/*
 * @Author: OBKoro1
 * @Date: 2019-09-24 20:25:33
 * LastEditors  : OBKoro1 // 字段会填充空格
 * LastEditTime : 2019-12-17 19:43:01  // 字段会填充空格
 * @FilePath: /fileHead/test.js
 */

wideNum为9，字段长度超出会导致长度不齐

/*
 * Author   : OBKoro1
 * Date     : 2019-09-24 20:25:33
 * LastEditors: OBKoro1
 * LastEditTime: 2019-12-17 10:35:19
 * FilePath : /fileHead/test.js
 */

函数注释等宽设置

"fileheader.configObj": {
    "functionWideNum": 0 // 0 默认关闭 设置一个正整数即可开启 比如12
}

开启效果

/**
 * @description 设置为13
 * @param       {*}
 * @return      {*}
 */
/**
 * @description 设置为0 关闭
 * @param {*}
 * @return {*}
 */

新建文件自动添加头部注释

"fileheader.configObj": {
  "createHeader": false // 默认关闭
}

插件匹配到language自定义语言注释配置、自定义注释配置时才会自动添加头部注释，如果匹配不到不会使用默认注释。

如果该文件被添加进黑名单，将不会自动添加头部注释。

这样在创建一些项目配置文件时，不会出现不必要的注释。

3. 头部注释第几行插入：

"fileheader.configObj": {
  "headInsertLine": {
    "php": 2, // php后缀的文件，在第二行插入文件头部注释
    "*": 3, // 所有文件都在第3行插入注释(除了php)
  }
}

规则：

默认都是将头部注释插入到第一行
格式就是上面演示的那样。
插入行数问题：文件行数不足设置的行数，注释将会插入到最后一行(下面有演示)

演示：

原文件(两行)：

<?php
?>

头部注释插入到第二行:

<?php
/*
 * @Author: OBKoro1
 * @Github: https://github.com/OBKoro1
 * @Date: 2018-12-21 10:49:35
 * @LastEditors: OBKoro1
 * @LastEditTime: 2018-12-21 17:06:07
 * @Description: 
 */
?>

头部注释插入到第3行，行数不足的演示：

<?php
?>/*
 * @Author: OBKoro1
 * @Github: https://github.com/OBKoro1
 * @Date: 2018-12-21 10:49:35
 * @LastEditors: OBKoro1
 * @LastEditTime: 2018-12-21 17:12:46
 * @Description: 
 */

4. Date字段时间选项：

当前时间/创建文件时间:

"fileheader.configObj": {
   "createFileTime": true, // 设为false更改为当前生成注释的时间
 }

头部注释：createFileTime默认为此文件的创建时间，将该字段设为false即可更改为当前注释的插入时间。

函数注释：V3.0 函数注释也支持Date字段了，该字段会生成函数注释插入的时间。

时间格式化：

"fileheader.configObj": {
   "dateFormat": "YYYY-MM-DD HH:mm:ss" // 默认格式
}

默认格式：

 * @Date: 2019-01-19 21:29:11

修改配置，可以精确自定义时间的格式，配置参数来自第三方：moment.js的format方法的参数。

比如：

"fileheader.configObj": {
  "dateFormat": "YYYY-MM-DD HH:mm:ss ZZ" // 输出：2019-05-20 15:42:07 +0800
}

PS：该功能将影响所有时间字段。

5. 头部注释前面插入内容：

"fileheader.configObj": {
  "beforeAnnotation": {
    "py": "#!/usr/bin/env python\n# coding=utf-8", // py文件默认，可修改
    "*": "\n" // 所有文件的头部注释都在前面增加一个换行(除了py)
  }
}

规则：

填写对应文件后缀，如py。
要添加的内容直接写进去就可以了，换行符\n

如这两个issue、issue中提到的，python文件头部还需要类似下面两行必备内容。

如上设置，最后在test.py文件中按头部注释的快捷键出现的效果是：

#!/usr/bin/env python
# coding=utf-8
'''
@Author: OBKoro1
@Date: 2019-02-18 13:03:37
@LastEditors: OBKoro1
@LastEditTime: 2019-02-19 12:26:24
'''

头部注释后面插入内容：

设置位置如下，其他规则跟上方《头部注释前面插入内容》的规则一样。

"fileheader.configObj": {
  "afterAnnotation": {
    "js": "// js文件头部注释之后的内容", 
    "*": "\n" // 所有文件新增头部注释之后都空一行(除了js)
  } // 需要特殊定制的文件后缀
}

6. 特殊字段允许自定义

目前在插件中头部注释的特殊字段：Author、Date、LastEditTime、LastEditors、Description、FilePath、

函数注释有三个特殊字段: description、param、return

类似Date字段，在静态博客中有自己定义的字段(如：updated_at)，不是Date。

也可以根据文件后缀，语言类型进行设置，你可以像下面这样设置：

  "fileheader.customMade":{
    "Author": "git config user.name && git config user.email",
    "Date": "Do not edit",
    "LastEditTime": "Do not edit",
    "LastEditors": "git config user.name && git config user.email",
    "FilePath": "Do not edit",
    "Description": "头部注释配置模板"
  },
  "fileheader.cursorMode":{
    "Description": "函数注释配置模板",
    "param": "",
    "return": ""
  },
"fileheader.configObj": {
  "specialOptions":{
    "Author": "creater",
    "Date": "since",
    "LastEditTime": "lastTime",
    "LastEditors": "LastAuthor",
    "Description": "message", // 头部注释大写的描述Description
    "description": "function message", // 函数注释小写的描述：description
    "FilePath": "文件相对于项目的路径"
    "param": "param2", // 函数注释parm参数别名
    // 文件后缀、或者语言后缀，可针对单个文件后缀进行配置：language的自定义语言配置
    "js": {
        "Description": "message2",  // 合并specialOptions第一层级的配置，覆盖Description的配置
        "return": "return2", // 单独为js文件添加return 特殊字段配置
    },
    "md": {
      "Date": "date",
      "Description": "tag"
    }
  }
}

默认为空对象，也就是不更改特殊字段。
你可以只设置一个对应的字段，也可都设置。
当你更改了特殊字段，那些使用老的特殊字段的注释，插件也进行过处理了，可以放心食用。
注意：如果是团队使用，需要团队成员一起修改。否则将不会自动更新最后编辑时间/最后编辑人以及打开自动添加注释的话，会检测不出来新的特殊字段，导致插件自动添加头部注释。
支持单独根据语言或者语言后缀进行配置，如上面配置中的js、md参考自定义语言的后缀形式

最后效果是：

/*
 * @creater: OBKoro1
 * @since: 2019-05-13 15:54:32
 * @lastTime: 2019-08-08 16:25:22
 * @LastAuthor: Do not edit
 * @文件相对于项目的路径: /testItem/src/index.js
 * @message2: 
 */
 /**
  * function message: 
  * param2 [type] param字段重命名
  * return2 [type] return字段重命名
  */
function test(a, b) {}

7. 在注释中输出一段自定义信息

在customMade/cursorMode中设置特殊属性custom_string_obkoro1~custom_string_obkoro100，用来输入一段自定义信息，设置如下：

PS：还有两个特殊字段custom_string_obkoro1_copyright(版权)、custom_string_obkoro1_date(时间)

  "fileheader.customMade": {
     "custom_string_obkoro1_date": "Do not edit", // 不带Date前缀的时间
    "Github": "https://github.com/OBKoro1",
    "custom_string_obkoro2": "custom_string_obkoro1~custom_string_obkoro100都可以输出自定义信息",
    "Author": "OBKoro1",
    // 版权声明 保留所有权利 自动替换年份 获取git config配置
    // 在本文档搜索git_name_email,获取如何配置以及如何配置公司和个人的user.name、user.email
    "custom_string_obkoro1_copyright": "Copyright (c) ${now_year} by ${git_name_email}, All Rights Reserved. "
    "custom_string_obkoro1": "可以输入预定的版权声明、个性签名、空行等"
  }

在test.js文件中的效果：

/** 
 * 2020-07-03 14:50:17 // 不带Date字段的时间
 * @Github: https://github.com/OBKoro1
 * custom_string_obkoro1~custom_string_obkoro100都可以输出自定义信息
 * @Author: OBKoro1
 * Copyright (c) 2022 by OBKoro1 [email protected], All Rights Reserved.  // 版权字段 在本文档搜索git_name_email,获取如何配置以及如何配置公司和个人的user.name、user.email
 * 可以输入预定的版权声明、个性签名、空行等 // 使用atSymbol字段可以去掉@
 */

8. 遇到换行添加注释符号

遇到\r\n、\n、\r换行情况时，自动在下一行开头添加应该有的注释标识符，设置如下：

// 设置
  "fileheader.customMade": {
    "Author": "OBKoro1",
     "test": "哈哈哈哈\n啦啦啦\r\n黑呵呵呵"
  }
// 效果 a.js
/*
 * @Author: OBKoro1
 * @---aaaa: 哈哈哈哈
 * 啦啦啦
 * 黑呵呵呵
 */

为避免出现问题，插件提供了一个开关来关闭它：

"fileheader.configObj": {
  "switch": {
    "newlineAddAnnotation": true // 默认开启
  }
}

移动光标到`Description :`所在行

"fileheader.configObj": {
    "moveCursor": true // 移动光标到`Description :`所在行
}

该选项默认开启
如果视图中没有注释，将会移动视图到顶部。
必须在customMade头部注释中有Description或者cursorMode函数中有description选项，没有该选项的话，将不生效。
Description、description可在configOptions.specialOptions中修改。

自定义注释中的艾特和冒号：

如下放注释中的@和: ,有几个issue中都提到了注释中的@和: 符号希望能够自定义

/*
 * @Author: OBKoro1
 * @Github: https://github.com/OBKoro1
 * @Date: 2019-05-13 15:54:32
 * @LastEditors: OBKoro1
 * @LastEditTime: 2019-05-13 15:54:32
 * @Description: 
 */

增加了以下四项配置，用以修改所有文件的@、: 以及单独修改某个文件类型的@和: ：

 "fileheader.configObj": {
    "atSymbol": [ "@", "@"], // 所有文件的头部注释和函数注释的默认值
    "atSymbolObj": {
      "js": ["", "@"], // .js文件的头部注释@符号去掉,所有文件的函数注释默认为@
      "java": [ "#", "@"] // .java文件 头部注释@改为#, 函数注释还是@
    },
    "colon": [ ": ", ": " ], // 所有文件的头部注释和函数注释的默认值
    "colonObj": {
      "js": [ " ", ": " ], // .js文件 头部注释去掉: 留一个空格 函数注释保留冒号
      "java": [ ": ", "$"] // .java文件 头部注释是冒号 函数注释是$
    }
  }

隐藏插件抛出的错误通知

"fileheader.configObj": {
  "showErrorMessage": false // 默认不显示错误通知 用于debugger
}

错误日志

"fileheader.configObj": {
  "writeLog": false // 默认不生成错误日志
}

开启错误日志后，每次重启vscode如果有报错都将会清空日志，这是防止日志过多的情况。

设置错误日志生成地址

按快捷键ctrl+p，调出命令行面板，输入以下命令即可选择文件夹设置日志地址。

>空格fileheader.errPathSet

单个文件保存时进行diff检查

每次保存之后，会进行一次diff检查, 如果文件只变更了LastEditors/LastEditTime，该文件将会回滚到本地仓库的最新版本.

"fileheader.configObj": {
  "CheckFileChange": false // 默认关闭
}

使用场景:

对文件进行修改之后又撤销，但是LastEditors和LastEditTime已经变更了，在提交代码的时候很容易忘记恢复它，导致无意义的提交，反正我很经常遇到这个问题。

运行逻辑：

检测VSCode当前打开的文件夹的根目录是否有.git文件夹, 没有的话，则退出
获取触发保存文件的diff，进行diff检查。
检测当只有LastEditors和LastEditTime变更，其他任何变更都没有的情况下。
将该文件回滚到本地仓库的最新版本。

关于功能的安全性：

鉴于之前该功能采用pre-commit的方案，造成过严重的BUG，新功能的破坏性会小很多，并且文件很容易就可以恢复：

目前该功能只针对单个文件进行操作，影响范围会比较小，并且挽回方式也比较简单快捷。

假如，我是说假如，再有出现文件被回滚的情况，因为这个操作是即时的，并且在每次保存都会触发，如果误将文件回滚了，在该文件上撤销一次即可将文件内容恢复恢复。

useWorker 区分工作区配置模板

"fileheader.configObj": {
  "useWorker": false // 默认关闭
}

如该issue通过该设置我们可以区分工作区设置的模板和用户设置的通用模板，默认情况下是合并工作区设置和用户设置的字段。

头部注释customMade 和函数注释cursorMode都可以区分。

函数注释自动提取函数的参数

开启的话，在cursorMode函数注释模板中需要有param字段

开启关闭自动提取添加函数参数

"fileheader.configObj": {
  "openFunctionParamsCheck": true // 默认开启
 }

函数注释参数提取使用:

单行函数声明参数提取

将鼠标光标放置于函数声明那一行，然后按函数注释快捷键生成

koroFileHeader函数参数提取

多行函数声明参数提取

鼠标左键选择多行函数声明区域，函数声明区域尽量精准，按快捷键生成

多行函数参数自动提取参数

目前支持函数参数自动提取的文件后缀：

支持语言

函数注释光标移动到下一行，快速添加函数参数描述

window: win+y, mac: cmd+y, linux: meta+y

生成函数注释之后，使用快捷键移动鼠标到下一行，快速为函数参数添加描述。

可能有很多参数，需要移动鼠标一个一个添加的话，操作起来有点麻烦。

函数注释光标移动到下一行，快速添加函数参数描述

自定义语言支持函数参数提取

在自定义语言的对象中使用functionParams字段，可以获取对应语言的解析函数参数的逻辑。

如果解析的逻辑不符合自定义语言的语法，那可以尝试其他语言的解析逻辑，应该会有合适。

"fileheader.configObj": {
    // 自定义语言
    "language": {
      "tsx": { // jsx后缀的文件
        "head": "/**",
        "middle": " * ",
        "end": "*/",
        "functionParams": "typescript" // 使用ts语言的解析逻辑
      }
    }
}

使用下列对象的key，即可获取对应语言解析函数参数的逻辑。

// 支持函数注释的语言
const supportLanguage = {
  javascript: 'function-js.js',
  javascriptreact: 'function-js.js', // react jsx
  vue: 'function-js.js', // vue
  html: 'function-js.js', // html
  typescript: 'function-ts.js', // ts
  typescriptreact: 'function-ts.js', // react tsx
  java: 'function-java.js', // java
  python: 'function-python.js', // py
  rust: 'function-rust.js', // rust
  go: 'function-go.js', // go
  c: 'function-c.js',
  cpp: 'function-c.js',
  php: 'function-php.js',
  solidity: 'function-solidity.js' // 智能合约的语言
}

函数内生成函数注释

设为true开启函数内生成函数注释，下面是设置示例：

"fileheader.configObj": {
  "cursorModeInternalAll": {
    "ts": true, // ts文件后缀是函数内生成函数注释
    "js": false, // js文件后缀是在函数外生成函数注释
    "python": true, // python语言类型文件时在函数内生成函数注释
    "defaultSetting": false // 默认是在函数外生成注释
  }
}

js文件示例示例：

/**
 * @description: 未开启：注释在函数外
 * @param {*} a
 * @param {*} b
 * @return {*}
 */
function test(a, b) {

}
// 某些语言的注释是写在函数内的
function test(a, b) {
/**
 * @description: 开启后：注释在函数内
 * @param {*} a
 * @param {*} b
 * @return {*}
 */

}

函数注释空格缩进

"fileheader.configObj": {
  "functionBlankSpaceAll": {} // 默认不缩进
}

// 配置示例
"fileheader.configObj": {
  // ... 其他配置
  // "functionBlankSpaceAll": {} // 默认为空对象 默认值为0 不缩进
    "functionBlankSpaceAll": {
      // "js": 2, // 单独设置文件：js文件后缀 缩进两格
      "python": 4, // 设置语言：python语言类型 函数注释空格缩进4格
      "defaultSetting": 0  // 不设置 默认值为0
    },
}

示例：

// js 不设置 默认不缩进
/**
 * @description  defaultSetting: 0 默认不缩进
 * @param a
 * @param b
 * @return {*}
 */
async function test(a, ...b) {}

# py缩进四格
def printinfo( arg1, **vardict ):
    '''
    @description:  python语言类型缩进4格
    @param arg1 [type]
    @param vardict [object]
    @return [type]
    '''

函数参数外形自定义

"fileheader.configObj": {
    "functionParamsShape": ["{", "}"]
    // "functionParamsShape": "no type" // 不需要参数类型
}

示例：

// functionParamsShape: [ "{", "}"] // 默认值
/**
 * @description: type包围起来的大括号: {}
 * @param {number} c
 * @param {string} b
 * @return {type}
 */
function test2(c: number, b: string = '2') {}
// functionParamsShape: [ "[", "]"]
/**
 * @description: 
 * @param [number] c
 * @param [string] b
 * @return [type]
 */
function test2(c: number, b: string = '2') {}
// functionParamsShape: "no type"
/**
 * @description: 
 * @param c
 * @param b
 * @return 
 */
function test2(c: number, b: string = '2') {}

参数没有类型时的默认值

"fileheader.configObj": {
    "functionTypeSymbol": "*"
}

// "functionTypeSymbol": "*" // 默认值
/**
 * @description: 
 * @param {*} axiosMethods
 * @param {*} apiLink
 * @param {*} opts
 * @param {*} fileName
 * @return {*}
 */
export const download = async (axiosMethods, apiLink, opts, fileName) => {};
// "functionTypeSymbol": "type"
/**
 * @description: 
 * @param {type} axiosMethods
 * @param {type} apiLink
 * @param {type} opts
 * @param {type} fileName
 * @return {type}
 */
export const download = async (axiosMethods, apiLink, opts, fileName) => {};
// "functionTypeSymbol": "match param no type" 
/**
 * @description: 这边匹配到param 但是没有type 正常是 [number] c [string] b
 * @param [] c
 * @param [] b
 * @return []
 */
function test2(c: number, b: string = '2') {}

参数类型和参数的位置自定义

"fileheader.configObj": {
    "typeParamOrder": "type param"
}

// "typeParamOrder": "type param" // 默认值
/**
 * @description: 类型在前面 参数在后面
 * @param {type} axiosMethods
 * @param {type} apiLink
 * @param {type} opts
 * @param {type} fileName
 * @return {type}
 */
export const download = async (axiosMethods, apiLink, opts, fileName) => {};
// "typeParamOrder": "param type"
/**
 * @description: 参数在前面 类型在后面 
 * @param axiosMethods {type}
 * @param apiLink {type}
 * @param opts {type}
 * @param fileName {type}
 * @return {type}
 */
export const download = async (axiosMethods, apiLink, opts, fileName) => {};

// "typeParamOrder": "param"
/**
 * @description: 只有参数 没有类型
 * @param axiosMethods
 * @param apiLink
 * @param opts
 * @param fileName
 * @return {type}
 */
export const download = async (axiosMethods, apiLink, opts, fileName) => {};

type param后面增加字符串

函数注释生成时在 type param 后面增加字符串可能是冒号，方便输入参数描述

"fileheader.configObj": {
  "functionParamAddStr": "" // 默认不增加字符串
}

示例:

// "functionParamAddStr": ":"
/**
 * @description: 增加冒号 方便输入参数描述
 * @param {type} a:
 * @param {type} b:
 * @param {array} c:
 * @return {type}
 */
function test2(a, b, ...c) {}

没有匹配到函数注释参数时是否显示param和return参数

NoMatchParams当没有匹配到函数注释参数时是否显示param和return

"fileheader.configObj": {
  "NoMatchParams": "no param" // 默认不显示param那一行
}

示例:

// "NoMatchParams": "no show param"
/**
 * @description: 没匹配到函数参数，不显示@param那行
 * @return {type} 填写返回值
 */

export const download = async ( ) => {
  // do something
  console.log('空参数 匹配不到函数参数: NoMatchParams')
  return 'something'
};

// "NoMatchParams": "no show param and return"
/**
 * @description: 只显示description 不显示@param与@return这两行
 */
export const download = async ( ) => {
  // do something
  console.log('空参数 匹配不到函数参数: NoMatchParams')
  return 'something'
};

// "NoMatchParams": "show param"
/**
 * @description: 没匹配到函数参数 也显示@param与@return
 * @param {type}
 * @return {type}
 */
export const download = async ( ) => {
  console.log('空参数 匹配不到函数参数: NoMatchParams')
};

自定义取消注释的head和end部分

注意该配置只在自定义语言注释language也配置了，才会生效

// 配置示例
"fileheader.configObj": {
  // ... 其他配置
  // "customHasHeadEnd": {} // 默认为空对象 默认都有head和end
  //  不设置自定义配置language无效
  "customHasHeadEnd": {
      "js": "cancel head and function", // 头部注释和函数注释均不取消head和end - 单独设置文件 js文件后缀
      "ts": "cancel function", // 函数注释不带有head和end-ts文件后缀
      "python": "cancel head", // 头部注释不带有head和end
      // "defaultSetting": ''  // 不设置 默认所有文件都有head和end
  },
}

示例：

// 配置:
"fileheader.configObj": {
    "language": {
      "js": {
        "head": "这里无效",
        "middle": "// ", // 设置中间部分即可
        "end": "这里无效"
      },
    },
  //  不设置自定义配置language无效
  "customHasHeadEnd": {
     "js": "cancel head and function", // 头部注释和函数注释均不取消head和end - 单独设置文件 js文件后缀
  }
}

// Author       : OBKoro1
// Date         : 2021-03-27 18:16:43
// LastEditors  : OBKoro1444
// LastEditTime : 2021-07-26 15:04:49
// FilePath     : test.js
// description  : 头部注释效果 需要设
// koroFileheader VSCode插件
// Copyright (c) 2021 by OBKoro1, All Rights Reserved.

// description: 函数注释效果
// param option [type]
// return [type]
function updateFillBuilderYAML(option) {}

节流时间自定义, 自定义同一个文件触发保存的频率

这个配置的意义在于，通过减少触发更新注释的方式，降低撤销更改重新保存后，导致被撤销内容被注释的更新所覆盖的问题 #358。

"fileheader.configObj": {
    "throttleTime": 60000 // 对同一个文件 需要过1分钟再次修改文件并保存才会更新注释
}

一个文件第一次修改内容并保存后，会触发更新注释的最后编辑人，最后编辑时间。

之后在该文件上进行修改，并且再次保存后，是否更新注释，取决于throttleTime所设定的时间。

当：（当前时间 - 上次执行事件 > throttleTime设定的时间），即触发更新注释函数。

PS：插件会保存最近30个文件的最后更新注释的时间，并使用LRU算法，在每次更新注释后，会将该文件更新成最新的。

用爱发电，求赞助 😭

开源不易，本插件的开发与维护全都是利用业余时间。

如果觉得这个效率工具还不错, 对你有所帮助，就赞助支持一下我的工作吧。

请我喝杯水吧，十块八块不嫌多，三块五块不嫌少 ❤️

如果觉得插件还不错，文档还蛮详细的，对你有所帮助的话，就点击右上角给我个Star ⭐️ 鼓励一下我吧~

配置

安装和快速上手

快速查阅功能

自动更新最后编辑时间、编辑人、文件路径：

图案注释

插件配置

整体功能

配置：

1. 自定义语言注释符号(可选项)：

用户自定义注释符号

language设置：

一次匹配多种文件后缀文件

有特殊要求的文件注释：

默认注释形式：

2. 自动添加文件头部注释:

autoAlready:只让支持的语言，自动添加头部注释

自动添加文件头部注释限制

自动添加头部注释文件白名单

自动添加头部注释黑名单

自动添加头部注释项目黑名单

文件超过一定行数不再自动添加头部注释

文件夹或文件名禁止自动添加头部注释

只允许文件自动添加头部注释一次：

FilePath:文件相对于项目的路径

filePathColon: 修改路径分隔符

Author和LastEditors获取git config配置

版权声明也支持读取git config配置

头部注释等宽设置wideSame

开启效果：

函数注释等宽设置

新建文件自动添加头部注释

3. 头部注释第几行插入：

4. Date字段时间选项：

当前时间/创建文件时间:

时间格式化：

5. 头部注释前面插入内容：

头部注释后面插入内容：

6. 特殊字段允许自定义

7. 在注释中输出一段自定义信息

8. 遇到换行添加注释符号

移动光标到Description :所在行

自定义注释中的艾特和冒号：

隐藏插件抛出的错误通知

错误日志

设置错误日志生成地址

单个文件保存时进行diff检查

关于功能的安全性：

useWorker 区分工作区配置模板

函数注释自动提取函数的参数

函数注释参数提取使用:

函数注释光标移动到下一行，快速添加函数参数描述

自定义语言支持函数参数提取

函数内生成函数注释

函数注释空格缩进

函数参数外形自定义

参数没有类型时的默认值

参数类型 和 参数的位置自定义

type param后面增加字符串

没有匹配到函数注释参数时是否显示param和return参数

自定义取消注释的head和end部分

节流时间自定义, 自定义同一个文件触发保存的频率

用爱发电，求赞助 😭

Clone this wiki locally

头部注释等宽设置`wideSame`

移动光标到`Description :`所在行

参数类型和参数的位置自定义