前言

最近在搞前端代码的文件注释，简单的记录一下jsDoc的使用方法，以及配置信息（前提是项目中以及有了eslint配置）。

什么是jsDoc

jsDoc是一个根据JavaScript 文件中的注释信息，生成JavaScript应用程序或模块的API文档的工具。你可以使用jsDoc标记如：命令空间，类，方法，方法参数等。从而使用开发者可以明白代码其中含义，降低维护成本，提高开发效率。

eslint-plugin-jsdoc 配置使用

配置eslint-plugin-jsdoc插件，来规范开发者在代码中的注释的编写，便于后期维护。

• 安装eslint-plugin-jsdoc依赖

npm install --save-dev eslint-plugin-jsdoc

• 配置.eslintrc.* 文件信息 在该文件中的overrides的数组中加入如下代码

  {
      files: ['**/IndicatorMangement/index.tsx'], // 想要使用该规则的文件
      plugins: ['jsdoc', 'header'], // jsdoc插件
      // extends: [
      //   'plugin:jsdoc/recommended'
      // ],
      rules: {
        // jsdoc注释规则
        'jsdoc/require-jsdoc': [
          'warn',
          {
            require: {
              ArrowFunctionExpression: true,
              ClassDeclaration: true,
              ClassExpression: true,
              FunctionExpression: true,
              MethodDefinition: true
            },
            contexts: ['TSInterfaceDeclaration'] // 检查接口是否写注释
          }
        ], // 检查函数是否写注释
        'jsdoc/check-alignment': 'warn', // 注释的*号是否对齐
        // 'jsdoc/check-examples': 'warn', // 在每个函数注释中要写一个@example fun()(如何使用这个函数)
        // 'jsdoc/check-indentation': 'warn', // 注释内有空格无效填充
        'jsdoc/check-param-names': ['warn'], // 检查函数参数名称和注释是否匹配
        'jsdoc/check-syntax': 'warn',
        'jsdoc/check-tag-names': 'warn', // 检查标签名是否有效
        // 'jsdoc/check-types': 'warn', // 报告无效类型
        'jsdoc/implements-on-classes': 'warn', //
        // 'jsdoc/match-description': [
        //   'warn',
        // ], // 对描述通过正则表单式匹配
        // 'jsdoc/newline-after-description': 'warn', // 在描述注释之后必须空一行
        // 'jsdoc/no-types': 'warn', // 不需要写类型
        // 'jsdoc/no-undefined-types': 'warn', // 写的类型不在规则里面
        'jsdoc/require-description': ['warn', { descriptionStyle: 'any' }], // 别要求写描述
        // 'jsdoc/require-description-complete-sentence': ['warn'], // 描述必须以大写开头.结尾
        // 'jsdoc/require-example': 'warn', // 别要求写例子
        // 'jsdoc/require-hyphen-before-param-description': 'warn', // 参数描述之前和描述之间必须-链接
        'jsdoc/require-param': 'warn', // 别要求写参数
        'jsdoc/require-param-description': 'warn', // 参数必须写描述
        'jsdoc/require-param-name': 'warn', // 参数必须写名字
        // 'jsdoc/require-param-type': 'warn', // 参数必须下类型jsdoc
        'jsdoc/require-returns': 'warn', // 要求写return注释
        // 'jsdoc/require-returns-check': 'warn', // 检查是否有必要写return注释
        'jsdoc/require-returns-description': 'warn', // 要求写return藐视
        // 'jsdoc/require-returns-type': 'warn', // 要求写return类型
        'jsdoc/valid-types': 'warn', // 有效的类型
      }
    }

或者可以使用推荐的配置

文件注释（eslint-plugin-header）

主要是针对文件头部的注释，可以检测文件头部是否写注释，检测书写注释的规范。

• 安装eslint-plugin-jsdoc依赖

npm install --save-dev eslint-plugin-header

• 配置.eslintrc.* 文件信息 在该文件中的overrides的数组中加入如下代码

  {
      files: ['**/IndicatorMangement/index.tsx'], // 想要使用该规则的文件
      plugins: ['jsdoc', 'header'], // jsdoc插件
      // extends: [
      //   'plugin:jsdoc/recommended'
      // ],
      rules: {
        // jsdoc注释规则
          'header/header': [ // 检查文件名是否有注释
          1,
          'block',
          [
            '',
            { pattern: ' @description: \\S', template: ' * @description: ' },
            { pattern: ' @author: \\w', template: ' * @author: ' },
            { pattern: ' @Date: \\S', template: ' * @Date: ' + moment(new Date()).format('YYYY-MM-DD HH:mm:ss') },
            ' '
          ]
        ]
      }
    }

安装插件koroFilerHeader

在vscode安装之后再setting自定义区加上下面代码

  "fileheader.customMade": {
    "description": "",
    "author": "li.kexin",
    "Date": "Do not edit" // 文件创建时间(不变)
  },
  "fileheader.cursorMode": {
    "description": "",
    "param": "",
    "returns": ""
  },

生成文件注释快捷键：Ctrl+Alt+i

/*
 * @description: 文件模块说明
 * @author: lilian
 * @Date: 2021-04-16 16:25:40
 */

生成函数注释快捷键：Ctrl+Alt+t

  /**
   * @description 函数说明
   * @param {number} a a参数说明
   * @returns {*} 返回值说明
   */
  const func = (a: number): number => {
    return a;
  };

总结

目前注释只做了现在函数和文件头部注释检测，接口注释配置了，但是满足不了项目中需求。如果有好的方法，请大家多多指教。