Package Exports

eslint-plugin-jsdoc

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (eslint-plugin-jsdoc) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

eslint-plugin-jsdoc

JSDoc specific linting rules for ESLint.

Attribution
Installation
Configuration
Rules

Attribution

Unusual, but I want to start the documentation with attribution to JSCS: JavaScript Code Style checker. This ESLint plugin is a wrapper around JSCS and the jscs-jsdoc plugin.

The reason for writing this plugin is to have all the linting rules in a consistent, plugin driven setup, that ESLint provides.

Thank you for your work JSCS.

Installation

Install ESLint either locally or globally.

$ npm install eslint

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

$ npm install 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/require-description-complete-sentence": 1,
        "jsdoc/require-param-description": 1
    }
}

Rules

`check-param-names`

Ensures param names in JSDoc and in function declaration are equal.

The following patterns are considered problems:

/**
 * @param foo
 * @param bar
 */
function fn (bar, foo) {

}

/**
 * @param foo
 */
function fn (bar) {

}

The following patterns are not considered problems:

/**
 * @param foo
 * @param bar
 */
function fn (foo, bar) {

}

/**
 * @param foo
 */
function fn (foo) {

}

`check-redundant-params`

Reports redundant params in JSDoc.

The following patterns are considered problems:

/**
 * @param {String} arg
 */
function fn () {}

The following patterns are not considered problems:

/**
 * @param {String} arg
 */
function fn (arg) {}

`check-redundant-returns`

Report statements for functions with no return.

The following patterns are considered problems:

/**
 * @returns {String}
 */
function fn () {

}

The following patterns are not considered problems:

/**
 * @returns {String}
 */
function fn () {
    return 'yes';
}

`require-return-types`

Ensures returns in JSDoc contains type.

The following patterns are considered problems:

/**
 * @returns
 */
function fn () {}

The following patterns are not considered problems:

/**
 * @returns {String}
 */
function fn () {}

/**
 * no @return
 */
function fn () {}

`newline-after-description`

Enforces consistent padding of doc comment description.

This rule takes one argument. If it is "always" then a problem is raised when there is a newline after description. If it is "never" then a problem is raised when there is no newline after the description. The default value is "always".

The following patterns are considered problems when configured "never":

/**
 * Description
 *
 * @param {String} arg
 */
function fn (arg) {}

The following patterns are not considered problems when configured "never":

/**
 * @param {String} arg
 */
function fn (arg) {}

/**
 * Description
 */
function fn () {}

/**
 * Description
 * @param {String} arg
 */
function fn (arg) {}

The following patterns are considered problems when configured "always":

/**
 * Description
 * @param {String} arg
 */
function fn (arg) {}

The following patterns are not considered problems when configured "always":

/**
 * @param {String} arg
 */
function fn (arg) {}

/**
 * Description
 */
function fn () {}

/**
 * Description
 *
 * @param {String} arg
 */
function fn (arg) {}

`require-description-complete-sentence`

Ensures a doc comment description is a complete sentence.

A complete sentence is defined as starting with an upper case letter and ending with a period.

The following patterns are considered problems:

/**
 * Description
 * On multiple lines.
 *
 * @param {String} arg
 */
function fn (arg) {}

/**
 * Description
 * @param {String} arg
 */
function fn (arg) {}

/**
 * description starting with a lower case letter.
 * @param {String} arg
 */
function fn (arg) {}

/**
 * Description period is offset .
 * @param {String} arg
 */
function fn (arg) {}

/**
 * Description!
 * @param {String} arg
 */
function fn (arg) {}

The following patterns are not considered problems:

/**
 * @param {String} arg
 */
function fn (arg) {}

/**
 * Description.
 */
function fn () {}

/**
 * (Description).
 */
function fn () {}

/**
 * Description.
 *
 * @param {String} arg
 */
function fn (arg) {}

`require-param-description`

Ensures a param description exists.

The following patterns are considered problems:

/**
 * @param {String} arg
 */
function fn (arg) {}

/**
 * @param arg
 */
function fn (arg) {}

The following patterns are not considered problems:

/**
 * @param {String} arg message
 */
function fn (arg) {}

/**
 * @param arg message
 */
function fn (arg) {}

`require-param-types`

The following patterns are considered problems:

/**
 * @param arg
 */
function fn () {}

The following patterns are not considered problems:

/**
 * @param {String} arg
 */
function fn () {}

`check-return-types`

Reports discrepancies between the claimed in JSDoc and actual type if both exist (code scan).

The following patterns are considered problems:

/**
 * @returns {String}
 */
function fn () {
    return true;
}

The following patterns are not considered problems:

/**
 * @returns {String}
 */
function fn () {
    return 'foo';
}