js-annotation

用于生成适用于 HTML 和 JS（包括 React、Vue 等三方库）的函数/文件注释。

比起其它的自定义注释插件，本插件更加简洁和轻巧，只包含了必备的description、param、reference等字段。

注释要素

注释撰写字段无需太多，否则会显得注释片段冗长而多余，如文件/方法名、作者、修改时间等字段就没必要书写，这些在 VS Code 中可通过GitLens插件查看。

就我个人而言，一个注释片段应包含以下要素:

• 方法/代码段描述(description)，必选，一句话描述该方法/代码段的功能和主要逻辑。不要太过宽泛和简略，如登录表单提交，这样没有意义。也不用逐行解释，这样费时又没必要。参考示例：登录表单提交，字段校验通过后调用接口将用户数据存至 store

• 函数参数列举(param)，函数有参时必选，用于描述该函数各接收参数的参数类型、参数名、参数说明、参数可选值等。如：user_type 用户类型 1 实习生 2 应届生 3 往届生

• 参考链接(reference)，api 方法必选，用于给出不方便详细描述的参考地址或者引用自互联网上某方法的原地址或者该 api 的接口文档地址。总之，给出参考链接的目的是提醒项目成员了解该代码段的详细说明和注意事项

注释风格

该插件的注释风格如下所示：

/**
 * @description 方法/代码段/文件描述
 * @param {参数类型} 参数名 参数描述
 * @reference 参考链接/接口文档地址/注意事项说明等
 */

插件使用

该插件使用的是 vscode 自定义用户代码段实现，通过输入插件暴露的关键属性，即可展示待选列表项和描述，如以输入js为例：

该插件所有的关键词和描述如下表所示：