Logo
Project Icon

eslint-plugin-jsdoc

ESLint 插件助力 JSDoc 规范化和质量控制

eslint-plugin-jsdocESLintJSDoc规则配置代码规范Github开源项目

eslint-plugin-jsdoc 是一个 ESLint 插件,用于检查和规范化 JSDoc 注释。它提供了丰富的规则集,可以验证标签使用、参数命名、类型声明等多个方面,并支持自动修复部分问题。该插件适用于 JavaScript 和 TypeScript 项目,通过灵活的配置选项,能够有效提升代码文档的一致性和准确性。

访问官网访问官网GithubGithub
介绍相关项目

eslint-plugin-jsdoc

NPM版本 Travis构建状态 js-canonical-style Discord聊天

ESLint的JSDoc lint规则。

安装

在本地或全局安装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的规则：

可能被添加到logical的规则：

可能被添加到contents的规则：

可能被添加到stylistic的规则：

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类型（可在设置中配置）
相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型，免费访问各种图像生成与AI训练工具，从Stable Diffusion等基础模型开始，轻松实现创新图像生成。体验前沿的AI技术，推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器，它将改变您观看视频的方式！SubCat结合了先进的人工智能技术，为您提供即时视频字幕翻译，无论是本地视频还是网络流媒体，让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台，利用前沿AI技术，为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图，再到文案生成，美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具，简化了选题、文献检索至论文撰写的整个过程。通过简单设定，平台可快速生成高质量论文大纲和全文，配合图表、参考文献等一应俱全，同时提供开题报告和答辩PPT等增值服务，保障数据安全，有效提升写作效率和论文质量。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号