eslint-plugin-jsdoc

ESLint的JSDoc lint规则。

• eslint-plugin-jsdoc
  • 安装
  • 配置
    • 平面配置
    • eslintrc
  • 选项
  • 设置
  • 高级
  • 处理器
  • 规则

安装

在本地或全局安装ESLint。

npm install --save-dev eslint

如果你已全局安装了ESLint，你也需要全局安装JSDoc插件。否则，请在本地安装。

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

配置

平面配置

import jsdoc from 'eslint-plugin-jsdoc';

const config = [
  // 插件中包含的配置
  jsdoc.configs['flat/recommended'],
  // 其他配置对象...
  {
    files: ['**/*.js'],
    plugins: {
      jsdoc,
    },
    rules: {
      'jsdoc/require-description': 'warn'
    }
  }
];

export default config;

在平面配置中可以扩展的通用起始规则集包括：

• jsdoc.configs['flat/recommended']：推荐的起始规则，用于强制执行正确的标签值、常见标签的存在，以及标签的格式和样式一致性
  • jsdoc.configs['flat/recommended-error']：相同的规则，但报告为失败错误而不是仅仅警告
• jsdoc.configs['flat/recommended-typescript']：类似的推荐起始列表，针对使用TypeScript语法的项目进行了调整（不仅仅是"typescript"mode设置）
  • jsdoc.configs['flat/recommended-typescript-error']：相同的规则，但报告为失败错误而不是仅仅警告
• jsdoc.configs['flat/recommended-typescript-flavor']：类似的推荐起始列表，针对使用JavaScript语法（源文件仍为.js）但在JSDoc中使用TypeScript风格的项目进行了调整（即eslint-plugin-jsdoc中默认的"typescript"mode）
  • jsdoc.configs['flat/recommended-typescript-flavor-error']：相同的规则，但报告为失败错误而不是仅仅警告

细粒度平面配置

还存在几个更细粒度的独立TypeScript规则集，你可以从中扩展。 这些规则集主要或仅启用了推荐起始规则中的部分规则：

• 内容：检查名称和描述的规则
  • jsdoc.configs['flat/contents-typescript']：用于TypeScript文件，报告设置为警告
  • jsdoc.configs['flat/contents-typescript-error']：用于TypeScript文件，报告设置为错误
  • jsdoc.configs['flat/contents-typescript-flavor']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为警告
  • jsdoc.configs['flat/contents-typescript-flavor-error']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为错误
• 逻辑：强制执行正确标签值的规则
  • jsdoc.configs['flat/logical-typescript']：用于TypeScript文件，报告设置为警告
  • jsdoc.configs['flat/logical-typescript-error']：用于TypeScript文件，报告设置为错误
  • jsdoc.configs['flat/logical-typescript-flavor']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为警告
  • jsdoc.configs['flat/logical-typescript-flavor-error']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为错误
• 要求：强制执行标签存在的规则
  • jsdoc.configs['flat/requirements-typescript']：用于TypeScript文件，报告设置为警告
  • jsdoc.configs['flat/requirements-typescript-error']：用于TypeScript文件，报告设置为错误
  • jsdoc.configs['flat/requirements-typescript-flavor']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为警告
  • jsdoc.configs['flat/requirements-typescript-flavor-error']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为错误
• 风格：强制执行清晰、一致的标签格式和样式的规则
  • jsdoc.configs['flat/stylistic-typescript']：用于TypeScript文件，报告设置为警告
  • jsdoc.configs['flat/stylistic-typescript-error']：用于TypeScript文件，报告设置为错误
  • jsdoc.configs['flat/stylistic-typescript-flavor']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为警告
  • jsdoc.configs['flat/stylistic-typescript-flavor-error']：用于使用JavaScript语法和JSDoc类型的文件，报告设置为错误

例如，要仅在TypeScript文件中强制执行JSDoc标签及其内容的有效性和一致性样式，而不强制要求标签必须始终存在：

import jsdoc from 'eslint-plugin-jsdoc';

export default [
  jsdoc.configs['flat/contents-typescript-error'],
  jsdoc.configs['flat/logical-typescript-error'],
  jsdoc.configs['flat/stylistic-typescript-error'],
];

为什么某些规则被排除在细粒度配置之外

有几个规则被排除在细粒度配置之外。原因如下：

可能被添加到required的规则：

• require-throws - 由于无法强制执行所有情况，某些人可能不希望强制执行此规则。
• require-file-overview - 对所有项目来说要求过高
• convert-to-jsdoc-comments - 对某些项目来说过于激进

可能被添加到logical的规则：

• no-missing-syntax - 没有默认选项。
• no-restricted-syntax - 没有默认选项。

可能被添加到contents的规则：

• match-name - 没有默认选项。
• require-description - 对所有项目来说要求过高
• require-description-complete-sentence - 对所有项目来说要求过高

可能被添加到stylistic的规则：

• check-indentation - 可能并非所有项目都需要
• sort-tags - 过于特定于项目

eslintrc

在.eslintrc.*中添加plugins部分，并将eslint-plugin-jsdoc指定为插件。

{
    "plugins": [
        "jsdoc"
    ]
}

最后，启用所有你想使用的规则。

{
    "rules": {
        "jsdoc/check-access": 1, // 推荐
        "jsdoc/check-alignment": 1, // 推荐
        "jsdoc/check-examples": 1,
        "jsdoc/check-indentation": 1,
        "jsdoc/check-line-alignment": 1,
        "jsdoc/check-param-names": 1, // 推荐
        "jsdoc/check-template-names": 1,
        "jsdoc/check-property-names": 1, // 推荐
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1, // 推荐
        "jsdoc/check-types": 1, // 推荐
        "jsdoc/check-values": 1, // 推荐
        "jsdoc/empty-tags": 1, // 推荐
        "jsdoc/implements-on-classes": 1, // 推荐
        "jsdoc/informative-docs": 1,
        "jsdoc/match-description": 1,
        "jsdoc/multiline-blocks": 1, // 推荐
        "jsdoc/no-bad-blocks": 1,
        "jsdoc/no-blank-block-descriptions": 1,
        "jsdoc/no-defaults": 1,
        "jsdoc/no-missing-syntax": 1,
        "jsdoc/no-multi-asterisks": 1, // 推荐
        "jsdoc/no-restricted-syntax": 1,
        "jsdoc/no-types": 1,
        "jsdoc/no-undefined-types": 1, // 推荐
        "jsdoc/require-asterisk-prefix": 1,
        "jsdoc/require-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-example": 1,
        "jsdoc/require-file-overview": 1,
        "jsdoc/require-hyphen-before-param-description": 1,
        "jsdoc/require-jsdoc": 1, // 推荐
        "jsdoc/require-param": 1, // 推荐
        "jsdoc/require-param-description": 1, // 推荐
        "jsdoc/require-param-name": 1, // 推荐
        "jsdoc/require-param-type": 1, // 推荐
        "jsdoc/require-property": 1, // 推荐
        "jsdoc/require-property-description": 1, // 推荐
        "jsdoc/require-property-name": 1, // 推荐
        "jsdoc/require-property-type": 1, // 推荐
        "jsdoc/require-returns": 1, // 推荐
        "jsdoc/require-returns-check": 1, // 推荐
        "jsdoc/require-returns-description": 1, // 推荐
        "jsdoc/require-returns-type": 1, // 推荐
        "jsdoc/require-template": 1,
        "jsdoc/require-throws": 1,
        "jsdoc/require-yields": 1, // 推荐
        "jsdoc/require-yields-check": 1, // 推荐
        "jsdoc/sort-tags": 1,
        "jsdoc/tag-lines": 1, // 推荐
        "jsdoc/valid-types": 1 // 推荐
    }
}

或者您可以简单地将以下内容添加到.eslintrc.*中，这将启用上面标记为"推荐"的规则：

{
  "extends": ["plugin:jsdoc/recommended"]
}

然后，您可以选择性地添加或覆盖推荐的规则。

或者，如果您希望将所有的检查问题报告为失败错误，可以使用"recommended-error"配置：

{
  "extends": ["plugin:jsdoc/recommended-error"]
}

如果您计划使用TypeScript语法（而不仅仅是使用"typescript"作为mode来指示JSDoc的风格是TypeScript），您可以使用：

{
  "extends": ["plugin:jsdoc/recommended-typescript"]
}

...或者报告为失败错误而不是简单的警告：

{
  "extends": ["plugin:jsdoc/recommended-typescript-error"]
}

如果您没有使用TypeScript语法（您的源文件仍然是.js文件），但您在JSDoc中使用TypeScript风格（即，eslint-plugin-jsdoc中默认的"typescript"mode），并且您可能使用TypeScript的tsconfig.json中的allowJs和checkJs选项，您可以使用：

{
  "extends": ["plugin:jsdoc/recommended-typescript-flavor"]
}

...或者报告为失败错误而不是简单的警告：

{
  "extends": ["plugin:jsdoc/recommended-typescript-flavor-error"]
}

选项

根据ESLint用户指南，规则可能有自己的独立选项。在eslint-plugin-jsdoc中，一些选项，如exemptedBy和contexts，可以在不同的规则中使用。

eslint-plugin-jsdoc的选项，如果存在，通常以对象的形式作为数组中错误级别之后的第二个参数提供（任何例外情况都在该规则的文档中解释）。

// `.eslintrc.js`
{
  rules: {
    'jsdoc/require-example': [
        // 错误级别应为`error`、`warn`或`off`（或2、1、0）
        'error',
        // 选项因规则而异，但通常添加到选项对象中，如下所示：
        {
          checkConstructors: true,
          exemptedBy: ['type']
        }
    ]
  }
}

设置

请参阅设置。

高级

请参阅高级。

处理器

请参阅我们的@example和其他项目处理器。

规则

下面带有扳手:wrench:的规则报告的问题可以通过在命令行上使用--fix选项运行ESLint来自动修复。 请注意，许多可修复的规则都有一个enableFixer选项，可以将其设置为false来禁用修复器（或者在check-param-names、check-property-names和no-blank-blocks这些规则中，将其设置为true来启用非默认推荐的修复器）。

推荐	可修复	规则	描述
:heavy_check_mark:		check-access	强制使用有效的 @access 标签
:heavy_check_mark:	:wrench:	check-alignment	强制 JSDoc 块星号对齐
		check-examples	对 @example 中的 JavaScript 进行 lint 检查
		check-indentation	检查 JSDoc 块内的无效缩进
	:wrench:	check-line-alignment	报告 JSDoc 块行的无效对齐。
:heavy_check_mark:	:wrench:	check-param-names	检查重复的 @param 名称，确保嵌套参数名有根，以及函数声明中的参数名与 jsdoc 参数名匹配。
:heavy_check_mark:	:wrench:	check-property-names	检查重复的 @property 名称，确保嵌套属性名有根
		check-syntax	根据当前模式报告使用情况（目前仅禁止 Closure 特定语法）
:heavy_check_mark:	:wrench:	check-tag-names	报告无效的 jsdoc（块）标签名
		check-template-names	检查任何 @template 名称是否在相关的 @typedef 或类型别名中实际使用。
:heavy_check_mark:	:wrench:	check-types	报告被视为无效的类型（可自定义，并有默认值，用于防止和/或推荐替换）
:heavy_check_mark:		check-values	检查一些杂项标签中的预期内容（@version、@since、@license、@author）
		convert-to-jsdoc-comments	将指定节点前后的行注释和块注释转换为 JSDoc 注释
:heavy_check_mark:	:wrench:	empty-tags	检查预期为空的标签（如 @abstract 或 @async），如果它们有内容则报告
:heavy_check_mark:		implements-on-classes	禁止在非构造函数上使用 @implements（以强制该标签仅用于类/构造函数）
		informative-docs	报告仅重述其附加名称的 JSDoc 文本。
		lines-before-block	强制 JSDoc 注释块前的最少换行数
		match-description	为标签描述定义可自定义的正则表达式规则
	:wrench:	match-name	如果 JSDoc 标签的名称部分匹配或不匹配给定的正则表达式则报告
:heavy_check_mark:	:wrench:	multiline-blocks	控制 jsdoc 块如何以及是否可以表示为单行或多行块
	:wrench:	no-bad-blocks	此规则检查不符合 jsdoc 块标准的多行样式注释
	:wrench:	no-blank-block-descriptions	如果存在标签，此规则将阻止块描述中的空行。如果没有标签，此规则将阻止块描述中的额外空行。
	:wrench:	no-blank-blocks	报告并可选择删除只包含空白的块
:heavy_check_mark:	:wrench:	no-defaults	此规则报告在 @param 或 @default 的相关部分使用默认值
		no-missing-syntax	此规则允许你报告是否缺少某些始终预期的注释结构。
:heavy_check_mark:	:wrench:	no-multi-asterisks	防止在行首使用多个星号
		no-restricted-syntax	当存在某些注释结构时报告
在 TS 中开启	:wrench:	no-types	禁止在 @param 或 @returns 上使用类型（与 TypeScript 重复）
:heavy_check_mark: (在 TS 和 TS 风格中关闭)		no-undefined-types	除了一些预期的内置类型外，禁止使用任何未在全局或 @typedef 中指定的类型
	:wrench:	require-asterisk-prefix	要求每个 JSDoc 行以 * 开头
		require-description	要求所有函数（以及可能的其他上下文）都有描述。
	:wrench:	require-description-complete-sentence	要求块描述、显式 @description 和 @param/@returns 标签描述使用完整句子
	:wrench:	require-example	要求所有函数（以及可能的其他上下文）都有示例。
		require-file-overview	默认情况下，要求在每个被 lint 的文件开头有一个单独的 @file 标签
	:wrench:	require-hyphen-before-param-description	要求在 @param 描述前使用连字符（可选地在 @property 描述前也使用）
:heavy_check_mark:	:wrench:	require-jsdoc	检查函数和其他上下文（可选限制为导出）中是否存在JSDoc注释。
:heavy_check_mark:	:wrench:	require-param	要求所有函数参数都使用@param标签进行文档说明。
:heavy_check_mark:		require-param-description	要求每个@param标签都有一个description值。
:heavy_check_mark:		require-param-name	要求所有@param标签都有名称。
:heavy_check_mark: (在TS中关闭)		require-param-type	要求每个@param标签都有类型值（在大括号内）。
:heavy_check_mark:	:wrench:	require-property	当@typedef和@namespace标签的类型是普通object、Object或PlainObject时，要求它们具有@property标签。
:heavy_check_mark:		require-property-description	要求每个@property标签都有一个description值。
:heavy_check_mark:		require-property-name	要求所有@property标签都有名称。
:heavy_check_mark: (在TS中关闭)		require-property-type	要求每个@property标签都有类型值（在大括号内）。
:heavy_check_mark:		require-returns	要求对返回语句进行文档说明。
:heavy_check_mark:		require-returns-check	如果JSDoc注释块中指定了@returns标签，则要求函数体中存在返回语句（并在存在多个@returns标签时报告）。
:heavy_check_mark:		require-returns-description	要求@returns标签有一个description值（不包括void/undefined类型的返回）。
:heavy_check_mark: (在TS中关闭)		require-returns-type	要求@returns标签有一个类型值（在大括号内）。
		require-template	当使用类型参数时，要求存在@template标签。
		require-throws	要求对throw语句进行文档说明
:heavy_check_mark:		require-yields	要求对yields进行文档说明
:heavy_check_mark:		require-yields-check	确保如果存在@yields，则函数体中存在yield（或带有值的yield）；或者如果存在@next，则存在带有返回值的yield
		sort-tags	根据标签名称按指定顺序对标签进行排序，可选择在标签组之间添加换行
:heavy_check_mark:	:wrench:	tag-lines	强制标签之间有（或没有）空行
	:wrench:	text-escaping	此规则可以自动转义在块和标签描述中输入的某些字符
:heavy_check_mark:		valid-types	要求所有类型/命名路径都是有效的JSDoc、Closure编译器或TypeScript类型（可在设置中配置）