eslint-plugin-jsdoc

Release 50.2.0

JSDoc linting rules for ESLint.

Homepage Repository npm JavaScript Download

Keywords
eslint, plugin, jsdoc, eslint-plugin-jsdoc
License
BSD-3-Clause
Install
npm install eslint-plugin-jsdoc@50.2.0

Documentation

eslint-plugin-jsdoc

NPM version Travis build status js-canonical-style Discord Chat

JSDoc linting rules for ESLint.

Installation

Install ESLint either locally or globally.

npm install --save-dev eslint

If you have installed ESLint globally, you have to install JSDoc plugin globally too. Otherwise, install it locally.

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

Configuration

Flat config

import jsdoc from 'eslint-plugin-jsdoc';

const config = [
  // configuration included in plugin
  jsdoc.configs['flat/recommended'],
  // other configuration objects...
  {
    files: ['**/*.js'],
    plugins: {
      jsdoc,
    },
    rules: {
      'jsdoc/require-description': 'warn'
    }
  }
];

export default config;

The general starting rulesets you can extend from in flat config are:

  • jsdoc.configs['flat/recommended']: Recommended starting rules for enforcing proper tag values, that common tags exist, and that tags are formatted and styled consistently
    • jsdoc.configs['flat/recommended-error']: The same, reporting with failing errors instead of mere warnings
  • jsdoc.configs['flat/recommended-typescript']: A similar recommended starting list, adjusted for projects using TypeScript syntax (and not just the "typescript" mode setting)
    • jsdoc.configs['flat/recommended-typescript-error']: The same, reporting with failing errors instead of mere warnings
  • jsdoc.configs['flat/recommended-typescript-flavor']: A similar recommended starting list, adjusted for projects using JavaScript syntax (source files that are still .js) but using TypeScript flavor within JSDoc (i.e., the default "typescript" mode in eslint-plugin-jsdoc)
    • jsdoc.configs['flat/recommended-typescript-flavor-error']: The same, reporting with failing errors instead of mere warnings

Granular Flat Configs

There also exist several more granular, standalone TypeScript rulesets you can extend from. These each only enable mostly or only rules from the recommended starting rules:

  • Contents: rules that check names and descriptions
    • jsdoc.configs['flat/contents-typescript']: for TypeScript files, with reports set to warn
    • jsdoc.configs['flat/contents-typescript-error']: for TypeScript files, with reports set to error
    • jsdoc.configs['flat/contents-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
    • jsdoc.configs['flat/contents-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error
  • Logical: rules that enforce proper tag values
    • jsdoc.configs['flat/logical-typescript']: for TypeScript files, with reports set to warn
    • jsdoc.configs['flat/logical-typescript-error']: for TypeScript files, with reports set to error
    • jsdoc.configs['flat/logical-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
    • jsdoc.configs['flat/logical-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error
  • Requirements: rules that enforce tags exist
    • jsdoc.configs['flat/requirements-typescript']: for TypeScript files, with reports set to warn
    • jsdoc.configs['flat/requirements-typescript-error']: for TypeScript files, with reports set to error
    • jsdoc.configs['flat/requirements-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
    • jsdoc.configs['flat/requirements-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error
  • Stylistic: rules that enforce clear, consistent tag formatting and styles
    • jsdoc.configs['flat/stylistic-typescript']: for TypeScript files, with reports set to warn
    • jsdoc.configs['flat/stylistic-typescript-error']: for TypeScript files, with reports set to error
    • jsdoc.configs['flat/stylistic-typescript-flavor']: for files using JavaScript syntax and JSDoc types, with reports set to warn
    • jsdoc.configs['flat/stylistic-typescript-flavor-error']: for files using JavaScript syntax and JSDoc types, with reports set to error

For example, to enforce only that any JSDoc tags and their contents are valid and styled consistently in TypeScript files, without enforcing that tags must always exist:

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'],
];

Why certain rules were excluded from the granular configs

A few rules were left out of the granular configs. Here is why:

Rules which might have been added to required:

Rules which might have been added to logical:

Rules which might have been added to contents:

Rules which might have been added to stylistic:

eslintrc

Add plugins section to .eslintrc.* and specify eslint-plugin-jsdoc as a plugin.

{
    "plugins": [
        "jsdoc"
    ]
}

Finally, enable all of the rules that you would like to use.

{
    "rules": {
        "jsdoc/check-access": 1, // Recommended
        "jsdoc/check-alignment": 1, // Recommended
        "jsdoc/check-examples": 1,
        "jsdoc/check-indentation": 1,
        "jsdoc/check-line-alignment": 1,
        "jsdoc/check-param-names": 1, // Recommended
        "jsdoc/check-template-names": 1,
        "jsdoc/check-property-names": 1, // Recommended
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1, // Recommended
        "jsdoc/check-types": 1, // Recommended
        "jsdoc/check-values": 1, // Recommended
        "jsdoc/empty-tags": 1, // Recommended
        "jsdoc/implements-on-classes": 1, // Recommended
        "jsdoc/informative-docs": 1,
        "jsdoc/match-description": 1,
        "jsdoc/multiline-blocks": 1, // Recommended
        "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, // Recommended
        "jsdoc/no-restricted-syntax": 1,
        "jsdoc/no-types": 1,
        "jsdoc/no-undefined-types": 1, // Recommended
        "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, // Recommended
        "jsdoc/require-param": 1, // Recommended
        "jsdoc/require-param-description": 1, // Recommended
        "jsdoc/require-param-name": 1, // Recommended
        "jsdoc/require-param-type": 1, // Recommended
        "jsdoc/require-property": 1, // Recommended
        "jsdoc/require-property-description": 1, // Recommended
        "jsdoc/require-property-name": 1, // Recommended
        "jsdoc/require-property-type": 1, // Recommended
        "jsdoc/require-returns": 1, // Recommended
        "jsdoc/require-returns-check": 1, // Recommended
        "jsdoc/require-returns-description": 1, // Recommended
        "jsdoc/require-returns-type": 1, // Recommended
        "jsdoc/require-template": 1,
        "jsdoc/require-throws": 1,
        "jsdoc/require-yields": 1, // Recommended
        "jsdoc/require-yields-check": 1, // Recommended
        "jsdoc/sort-tags": 1,
        "jsdoc/tag-lines": 1, // Recommended
        "jsdoc/valid-types": 1 // Recommended
    }
}

Or you can simply add the following to .eslintrc.*, which enables the rules commented above as "recommended":

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

You can then selectively add to or override the recommended rules.

Alternatively, if you wish to have all linting issues reported as failing errors, you may use the "recommended-error" config:

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

If you plan to use TypeScript syntax (and not just "typescript" mode to indicate the JSDoc flavor is TypeScript), you can use:

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

...or to report with failing errors instead of mere warnings:

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

If you are not using TypeScript syntax (your source files are still .js files) but you are using the TypeScript flavor within JSDoc (i.e., the default "typescript" mode in eslint-plugin-jsdoc) and you are perhaps using allowJs and checkJs options of TypeScript's tsconfig.json), you may use:

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

...or to report with failing errors instead of mere warnings:

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

Options

Rules may, as per the ESLint user guide, have their own individual options. In eslint-plugin-jsdoc, a few options, such as, exemptedBy and contexts, may be used across different rules.

eslint-plugin-jsdoc options, if present, are generally in the form of an object supplied as the second argument in an array after the error level (any exceptions to this format are explained within that rule's docs).

// `.eslintrc.js`
{
  rules: {
    'jsdoc/require-example': [
        // The Error level should be `error`, `warn`, or `off` (or 2, 1, or 0)
        'error',
        // The options vary by rule, but are generally added to an options
        //  object as follows:
        {
          checkConstructors: true,
          exemptedBy: ['type']
        }
    ]
  }
}

Settings

See Settings.

Advanced

See Advanced.

Processors

See our @example and other item processors.

Rules

Problems reported by rules which have a wrench 🔧 below can be fixed automatically by running ESLint on the command line with --fix option.

Note that a number of fixable rules have an enableFixer option which can be set to false to disable the fixer (or in the case of check-param-names, check-property-names, and no-blank-blocks, set to true to enable a non-default-recommended fixer).

recommended fixable rule description
✔️ check-access Enforces valid @access tags
✔️ 🔧 check-alignment Enforces alignment of JSDoc block asterisks
check-examples Linting of JavaScript within @example
check-indentation Checks for invalid padding inside JSDoc blocks
🔧 check-line-alignment Reports invalid alignment of JSDoc block lines.
✔️ 🔧 check-param-names Checks for dupe @param names, that nested param names have roots, and that parameter names in function declarations match jsdoc param names.
✔️ 🔧 check-property-names Checks for dupe @property names, that nested property names have roots
check-syntax Reports use against current mode (currently only prohibits Closure-specific syntax)
✔️ 🔧 check-tag-names Reports invalid jsdoc (block) tag names
check-template-names Checks that any @template names are actually used in the connected @typedef or type alias.
✔️ 🔧 check-types Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements)
✔️ check-values Checks for expected content within some miscellaneous tags (@version, @since, @license, @author)
convert-to-jsdoc-comments Converts line and block comments preceding or following specified nodes into JSDoc comments
✔️ 🔧 empty-tags Checks tags that are expected to be empty (e.g., @abstract or @async), reporting if they have content
✔️ implements-on-classes Prohibits use of @implements on non-constructor functions (to enforce the tag only being used on classes/constructors)
informative-docs Reports on JSDoc texts that serve only to restate their attached name.
lines-before-block Enforces minimum number of newlines before JSDoc comment blocks
match-description Defines customizable regular expression rules for your tag descriptions
🔧 match-name Reports the name portion of a JSDoc tag if matching or not matching a given regular expression
✔️ 🔧 multiline-blocks Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks
🔧 no-bad-blocks This rule checks for multi-line-style comments which fail to meet the criteria of a jsdoc block
🔧 no-blank-block-descriptions If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description.
🔧 no-blank-blocks Reports and optionally removes blocks with whitespace only
✔️ 🔧 no-defaults This rule reports defaults being used on the relevant portion of @param or @default
no-missing-syntax This rule lets you report if certain always expected comment structures are missing.
✔️ 🔧 no-multi-asterisks Prevents use of multiple asterisks at the beginning of lines
no-restricted-syntax Reports when certain comment structures are present
On in TS 🔧 no-types Prohibits types on @param or @returns (redundant with TypeScript)
✔️ (off in TS and TS flavor) no-undefined-types Besides some expected built-in types, prohibits any types not specified as globals or within @typedef
🔧 require-asterisk-prefix Requires that each JSDoc line starts with an *
require-description Requires that all functions (and potentially other contexts) have a description.
🔧 require-description-complete-sentence Requires that block description, explicit @description, and @param/@returns tag descriptions are written in complete sentences
🔧 require-example Requires that all functions (and potentially other contexts) have examples.
require-file-overview By default, requires a single @file tag at the beginning of each linted file
🔧 require-hyphen-before-param-description Requires a hyphen before @param descriptions (and optionally before @property descriptions)
✔️ 🔧 require-jsdoc Checks for presence of jsdoc comments, on functions and potentially other contexts (optionally limited to exports).
✔️ 🔧 require-param Requires that all function parameters are documented with a @param tag.
✔️ require-param-description Requires that each @param tag has a description value.
✔️ require-param-name Requires that all @param tags have names.
✔️ (off in TS) require-param-type Requires that each @param tag has a type value (within curly brackets).
✔️ 🔧 require-property Requires that all @typedef and @namespace tags have @property tags when their type is a plain object, Object, or PlainObject.
✔️ require-property-description Requires that each @property tag has a description value.
✔️ require-property-name Requires that all @property tags have names.
✔️ (off in TS) require-property-type Requires that each @property tag has a type value (within curly brackets).
✔️ require-returns Requires that return statements are documented.
✔️ require-returns-check Requires a return statement be present in a function body if a @returns tag is specified in the jsdoc comment block (and reports if multiple @returns tags are present).
✔️ require-returns-description Requires that the @returns tag has a description value (not including void/undefined type returns).
✔️ (off in TS) require-returns-type Requires that @returns tag has a type value (in curly brackets).
require-template Requires @template tags be present when type parameters are used.
require-throws Requires that throw statements are documented
✔️ require-yields Requires that yields are documented
✔️ require-yields-check Ensures that if a @yields is present that a yield (or yield with a value) is present in the function body (or that if a @next is present that there is a yield with a return value present)
sort-tags Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups
✔️ 🔧 tag-lines Enforces lines (or no lines) between tags
🔧 text-escaping This rule can auto-escape certain characters that are input within block and tag descriptions
✔️ valid-types Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings)

Stats

Dependencies
11
Dependent packages
10.7K
Dependent repositories
5.88K
Total releases
662
Latest release
First release
Stars
1.1K
Forks
159
Watchers
7
Contributors
102
Repository size
6.72 MB
SourceRank
25

Development practices

Source repo 2FA enabled
TEXT!
Package manager 2FA enabled
TEXT!
Is security responsive
TEXT!
Dependencies are managed
TEXT!
Issue-free release available
TEXT!
Succession plan available
TEXT!

The Tidelift Subscription provides access to a continuously curated stream of human-researched and maintainer-verified data on open source packages and their licenses, releases, vulnerabilities, and development practices.

Learn more →

Releases

50.5.0
50.4.3
50.4.2
50.4.1
50.4.0
50.3.2
50.3.1
50.3.0
50.2.5
50.2.4
See all 662 releases

Contributors

Brett Zamir Gajus Kuizinas Chiawen Chen Kalashnikov Ilya Patryk Rzucidło Josh Goldberg ✨ Dylan Staley YeonJuan Remco Haszing Extersky Renatho De Carli Rosa Chris Thomas Schmid dependabot[bot] Bary Levi Nathan Shively-Sanders Simon Seyock Marcin Konicki Jasmine Xie Andrew Leedham Eric Wang Frazer Smith Kenton Jacobsen Nick Schonning


See all contributors

Login to resync this project