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
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.
Reference to jscs-jsdoc
This table maps the rules between eslint-plugin-jsdoc and jscs-jsdoc.
Installation
Install ESLint either locally or globally.
$ npm install eslintIf you have installed ESLint globally, you have to install JSDoc plugin globally too. Otherwise, install it locally.
$ npm install eslint-plugin-jsdocConfiguration
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-param-names": 1,
"jsdoc/check-redundant-params": 1,
"jsdoc/check-redundant-returns": 1,
"jsdoc/check-returns-types": 1,
"jsdoc/check-types": 1,
"jsdoc/newline-after-description": 1,
"jsdoc/require-description-complete-sentence": 1,
"jsdoc/require-param": 1,
"jsdoc/require-param-description": 1,
"jsdoc/require-param-types": 1,
"jsdoc/require-returns-description": 1,
"jsdoc/require-returns-types": 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 quux (bar, foo) {
}
/**
* @param foo
*/
function quux (bar) {
}The following patterns are not considered problems:
/**
* @param foo
* @param bar
*/
function quux (foo, bar) {
}
/**
* @param foo
*/
function quux (foo) {
}check-redundant-params
Reports redundant params in JSDoc.
The following patterns are considered problems:
/**
* @param {string} foo
*/
function quux () {
}The following patterns are not considered problems:
/**
* @param {string} foo
*/
function quux (foo) {
}check-redundant-returns
Report statements for functions with no return.
The following patterns are considered problems:
/**
* @returns {string}
*/
function quux () {
}The following patterns are not considered problems:
/**
* @returns {string}
*/
function quux () {
return 'corge';
}check-returns-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 quux () {
return true;
}The following patterns are not considered problems:
/**
* @returns {string}
*/
function quux () {
return 'corge';
}check-types
Reports invalid types. Ensures that case of natives is the same as in this list:
boolean
number
string
Object
Array
Date
RegExpThe following patterns are considered problems:
/**
* @param {Boolean} foo
*/
function quux (foo) {
}
/**
* @param {date} foo
*/
function quux (foo) {
}The following patterns are not considered problems:
/**
* @param {boolean} foo
*/
function quux (foo) {
}
/**
* @param {Date} foo
*/
function quux (foo) {
}
/**
* @typedef foo~bar
*/
/**
* @param {foo~bar} bar
*/
function quux (foo) {
}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} foo
*/
function quux (foo) {
}The following patterns are not considered problems when configured "never":
/**
* @param {string} foo
*/
function quux (foo) {
}
/**
* Description
*/
function quux () {
}
/**
* Description
* @param {string} foo
*/
function quux (foo) {
}The following patterns are considered problems when configured "always":
/**
* Description
* @param {string} foo
*/
function quux (foo) {
}The following patterns are not considered problems when configured "always":
/**
* @param {string} foo
*/
function quux (foo) {
}
/**
* Description
*/
function quux () {
}
/**
* Description
*
* @param {string} foo
*/
function quux (foo) {
}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} foo
*/
function quux (foo) {
}
/**
* Description
* @param {string} foo
*/
function quux (foo) {
}
/**
* description starting with a lower case letter.
* @param {string} foo
*/
function quux (foo) {
}
/**
* Description period is offset .
* @param {string} foo
*/
function quux (foo) {
}
/**
* Description!
* @param {string} foo
*/
function quux (foo) {
}The following patterns are not considered problems:
/**
* @param {string} foo
*/
function quux (foo) {
}
/**
* Description.
*/
function quux () {
}
/**
* (Description).
*/
function quux () {
}
/**
* Description.
*
* @param {string} foo
*/
function quux (foo) {
}require-param
Ensures all parameters are documented.
The following patterns are considered problems:
/**
*
*/
function quux (foo) {
}The following patterns are not considered problems:
/**
* @param {string} foo
*/
function quux (foo) {
}require-param-description
Ensures a param description exists.
The following patterns are considered problems:
/**
* @param {string} foo
*/
function quux (foo) {}
/**
* @param foo
*/
function quux (foo) {
}The following patterns are not considered problems:
/**
* @param {string} foo Foo.
*/
function quux (foo) {
}
/**
* @param foo Foo.
*/
function quux (foo) {
}require-param-types
The following patterns are considered problems:
/**
* @param foo
*/
function quux () {
}The following patterns are not considered problems:
/**
* @param {string} foo
*/
function quux () {
}require-returns-description
Ensures a @returns description exists.
The following patterns are considered problems:
/**
* @returns {string}
*/
function quux () {
}The following patterns are not considered problems:
/**
* @returns {string} Quux.
*/
function quux () {
}require-returns-types
Ensures @returns in JSDoc contains type.
The following patterns are considered problems:
/**
* @returns
*/
function quux () {
}The following patterns are not considered problems:
/**
* @returns {string}
*/
function quux () {
}
/**
* no @returns
*/
function quux () {
}