README.md

eslint-plugin-jsdoc

JSDoc linting rules for ESLint.

{"gitdown": "contents"}

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

Add plugins section 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-alignment": 1, // Recommended
        "jsdoc/check-examples": 1,
        "jsdoc/check-indentation": 1,
        "jsdoc/check-param-names": 1, // Recommended
        "jsdoc/check-syntax": 1,
        "jsdoc/check-tag-names": 1, // Recommended
        "jsdoc/check-types": 1, // Recommended
        "jsdoc/implements-on-classes": 1, // Recommended
        "jsdoc/match-description": 1,
        "jsdoc/newline-after-description": 1, // Recommended
        "jsdoc/no-types": 1,
        "jsdoc/no-undefined-types": 1, // Recommended
        "jsdoc/require-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-example": 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-returns": 1, // Recommended
        "jsdoc/require-returns-check": 1, // Recommended
        "jsdoc/require-returns-description": 1, // Recommended
        "jsdoc/require-returns-type": 1, // Recommended
        "jsdoc/valid-types": 1 // Recommended
    }
}

Or you can simply use the following which enables the rules commented above as "recommended":

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

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

Settings

Allow @private to disable rules for that comment block

• settings.jsdoc.ignorePrivate - Disables all rules for the comment block on which a @private tag occurs. Defaults to false.

Mode

• settings.jsdoc.mode - Set to jsdoc (the default), typescript, or closure. Currently is used for the following:
  • Determine valid tags for check-tag-names
  • Only check @template in no-undefined-types for types in "closure" and "typescript" modes
  • For type-checking rules, determine which tags will be checked for types (Closure allows types on some tags which the others do not, so these tags will additionally be checked in "closure" mode)
  • Check preferred tag names

Alias Preference

Use settings.jsdoc.tagNamePreference to configure a preferred alias name for a JSDoc tag. The format of the configuration is: <primary tag name>: <preferred alias name>, e.g.

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "tagNamePreference": {
                "param": "arg",
                "returns": "return"
            }
        }
    }
}

One may also use an object with a message and replacement.

The following will report the message @extends is to be used over @augments as it is more evocative of classes than @augments upon encountering @augments.

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "tagNamePreference": {
                "augments": {
                  "message": "@extends is to be used over @augments as it is more evocative of classes than @augments",
                  "replacement": "extends"
                }
            }
        }
    }
}

If one wishes to reject a normally valid tag, e.g., @todo, one may set the tag to false:

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "tagNamePreference": {
                "todo": false
            }
        }
    }
}

Or one may set the targeted tag to an object with a custom message, but without a replacement property:

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "tagNamePreference": {
                "todo": {
                  "message": "We expect immediate perfection, so don't leave to-dos in your code."
                }
            }
        }
    }
}

Note that the preferred tags indicated in the settings.jsdoc.tagNamePreference map will be assumed to be defined by check-tag-names.

The defaults in eslint-plugin-jsdoc (for tags which offer aliases) are as follows:

• @abstract (over @virtual)
• @augments (over @extends)
• @class (over @constructor)
• @constant (over @const)
• @default (over @defaultvalue)
• @description (over @desc)
• @external (over @host)
• @file (over @fileoverview, @overview)
• @fires (over @emits)
• @function (over @func, @method)
• @member (over @var)
• @param (over @arg, @argument)
• @property (over @prop)
• @returns (over @return)
• @throws (over @exception)
• @yields (over @yield)

This setting is utilized by the the rule for tag name checking (check-tag-names) as well as in the @param and @require rules:

• check-param-names
• check-tag-names
• require-hyphen-before-param-description
• require-description
• require-param
• require-param-description
• require-param-name
• require-param-type
• require-returns
• require-returns-check
• require-returns-description
• require-returns-type

@override/@augments/@extends/@implements Without Accompanying @param/@description/@example/@returns

The following settings allows the element(s) they reference to be omitted on the JSDoc comment block of the function or that of its parent class for any of the "require" rules (i.e., require-param, require-description, require-example, or require-returns).

• settings.jsdoc.overrideReplacesDocs (@override) - Defaults to true
• settings.jsdoc.augmentsExtendsReplacesDocs (@augments or its alias @extends) - Defaults to false.
• settings.jsdoc.implementsReplacesDocs (@implements) - Defaults to false

The format of the configuration is as follows:

{
    "rules": {},
    "settings": {
        "jsdoc": {
            "overrideReplacesDocs": true,
            "augmentsExtendsReplacesDocs": true,
            "implementsReplacesDocs": true
        }
    }
}

Settings to Configure check-types and no-undefined-types

• settings.jsdoc.preferredTypes An option map to indicate preferred or forbidden types (if default types are indicated here, these will have precedence over the default recommendations for check-types). The keys of this map are the types to be replaced (or forbidden). These keys may include:

  1. The "ANY" type, *
  2. The pseudo-type [] which we use to denote the parent (array) types used in the syntax string[], number[], etc.
  3. The pseudo-type .<> (or .) to represent the format Array.<value> or Object.<key, value>
  4. The pseudo-type <> to represent the format Array<value> or Object<key, value>
  5. A plain string type, e.g., MyType
  6. A plain string type followed by one of the above pseudo-types (except for [] which is always assumed to be an Array), e.g., Array., or SpecialObject<>.

  If a bare pseudo-type is used, it will match all parent types of that form. If a pseudo-type prefixed with a type name is used, it will only match parent types of that form and type name.

  The values can be:

  • false to forbid the type
  • a string to indicate the type that should be preferred in its place (and which fix mode can replace); this can be one of the formats of the keys described above. Note that the format will not be changed unless you use a pseudo-type in the replacement (e.g., 'Array.<>': 'MyArray' will change Array.<string> to MyArray.<string>, preserving the dot; to get rid of the dot, you must use the pseudo-type: 'Array.<>': 'MyArray<>' which will change Array.<string> to MyArray<string>). If you use a bare pseudo-type in the replacement, e.g., 'MyArray.<>': '<>', the type will be converted to the format of the pseudo-type without changing the type name, i.e., MyArray.<string> will become MyArray<string> but Array.<string> will not be modified.
  • an object with the key message to provide a specific error message when encountering the discouraged type and, if a type is to be preferred in its place, the key replacement to indicate the type that should be used in its place (and which fix mode can replace) or false if forbidding the type. The message string will have the substrings with special meaning, {{tagName}} and {{tagValue}}, replaced with their corresponding value.

Note that the preferred types indicated as targets in settings.jsdoc.preferredTypes map will be assumed to be defined by no-undefined-types.

See the option of check-types, unifyParentAndChildTypeChecks, for how the keys of preferredTypes may have <> or .<> (or just .) appended and its bearing on whether types are checked as parents/children only (e.g., to match Array if the type is Array vs. Array.<string>).

Rules

{"gitdown": "include", "file": "./rules/check-alignment.md"} {"gitdown": "include", "file": "./rules/check-examples.md"} {"gitdown": "include", "file": "./rules/check-indentation.md"} {"gitdown": "include", "file": "./rules/check-param-names.md"} {"gitdown": "include", "file": "./rules/check-syntax.md"} {"gitdown": "include", "file": "./rules/check-tag-names.md"} {"gitdown": "include", "file": "./rules/check-types.md"} {"gitdown": "include", "file": "./rules/implements-on-classes.md"} {"gitdown": "include", "file": "./rules/match-description.md"} {"gitdown": "include", "file": "./rules/newline-after-description.md"} {"gitdown": "include", "file": "./rules/no-types.md"} {"gitdown": "include", "file": "./rules/no-undefined-types.md"} {"gitdown": "include", "file": "./rules/require-description-complete-sentence.md"} {"gitdown": "include", "file": "./rules/require-description.md"} {"gitdown": "include", "file": "./rules/require-example.md"} {"gitdown": "include", "file": "./rules/require-hyphen-before-param-description.md"} {"gitdown": "include", "file": "./rules/require-jsdoc.md"} {"gitdown": "include", "file": "./rules/require-param-description.md"} {"gitdown": "include", "file": "./rules/require-param-name.md"} {"gitdown": "include", "file": "./rules/require-param-type.md"} {"gitdown": "include", "file": "./rules/require-param.md"} {"gitdown": "include", "file": "./rules/require-returns-check.md"} {"gitdown": "include", "file": "./rules/require-returns-description.md"} {"gitdown": "include", "file": "./rules/require-returns-type.md"} {"gitdown": "include", "file": "./rules/require-returns.md"} {"gitdown": "include", "file": "./rules/valid-types.md"}