eslint-plugin-jsdoc

What is eslint-plugin-jsdoc?

The eslint-plugin-jsdoc package is a plugin for ESLint that provides linting rules for JSDoc comments. JSDoc is a markup language used to annotate JavaScript source code files. Using eslint-plugin-jsdoc, developers can ensure that their JSDoc comments are consistent and follow best practices.

What are eslint-plugin-jsdoc's main functionalities?

Check alignment

Ensures that JSDoc blocks are aligned properly.

/* eslint jsdoc/check-alignment: "error" */
/**
 * Function description.
 *
 * @param {string} name - The name of the person.
 * @return {string} - The greeting message.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

Check indentation

Ensures that JSDoc blocks have consistent indentation.

/* eslint jsdoc/check-indentation: "error" */
/**
 * Function description.
 *
 * @param {string} name - The name of the person.
 * @return {string} - The greeting message.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

Check types

Validates JSDoc comments for type correctness.

/* eslint jsdoc/check-types: "error" */
/**
 * Function description.
 *
 * @param {String} name - The name of the person.
 * @return {String} - The greeting message.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

Require JSDoc

Requires JSDoc comments for certain nodes in the code.

/* eslint jsdoc/require-jsdoc: "error" */
/**
 * Function description.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

Other packages similar to eslint-plugin-jsdoc

tsdoc

TSDoc is a documentation comment format used for TypeScript source files. It is similar to JSDoc but tailored for the TypeScript language, providing a standardized way to document TypeScript APIs. Unlike eslint-plugin-jsdoc, TSDoc does not provide linting rules but focuses on the comment format itself.

documentation

The 'documentation' package is a documentation generator that uses JSDoc comments to produce documentation for JavaScript code. It is similar to eslint-plugin-jsdoc in that it processes JSDoc comments, but its primary purpose is to generate documentation rather than lint code.

typedoc

TypeDoc is a documentation generator for TypeScript projects. It reads TypeScript source files and JSDoc comments to produce documentation. While eslint-plugin-jsdoc focuses on linting JSDoc comments, TypeDoc uses them to generate documentation websites or markdown files.

README

eslint-plugin-jsdoc

JSDoc linting rules for ESLint.

• eslint-plugin-jsdoc
  • Reference to jscs-jsdoc
  • Installation
  • Configuration
  • Settings
    • Alias Preference
  • Rules
    • check-param-names
    • check-tag-names
    • check-types
    • newline-after-description
    • require-description-complete-sentence
    • require-param-description
    • require-param
    • require-param-description
    • require-param-type
    • require-returns-description
    • require-returns-type

Reference to jscs-jsdoc

This table maps the rules between eslint-plugin-jsdoc and jscs-jsdoc.

eslint-plugin-jsdoc	jscs-jsdoc
check-param-names	checkParamNames
check-tag-names	N/A ~ checkAnnotations
check-types	checkTypes
newline-after-description	requireNewlineAfterDescription and disallowNewlineAfterDescription
require-description-complete-sentence	requireDescriptionCompleteSentence
require-hyphen-before-description	requireHyphenBeforeDescription
require-param	checkParamExistence
require-param-description	requireParamDescription
require-param-type	requireParamTypes
require-returns-description	requireReturnDescription
require-returns-type	requireReturnTypes
N/A	checkReturnTypes
N/A	checkRedundantParams
N/A	checkReturnTypes
N/A	checkRedundantAccess
N/A	enforceExistence
N/A	leadingUnderscoreAccess

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/check-param-names": 1,
        "jsdoc/check-tag-names": 1,
        "jsdoc/check-types": 1,
        "jsdoc/newline-after-description": 1,
        "jsdoc/require-description-complete-sentence": 1,
        "jsdoc/require-hyphen-before-description": 1,
        "jsdoc/require-param": 1,
        "jsdoc/require-param-description": 1,
        "jsdoc/require-param-type": 1,
        "jsdoc/require-returns-description": 1,
        "jsdoc/require-returns-type": 1
    }
}

Settings

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"
            }
        }
    }
}

Rules

check-param-names

Ensures that parameter names in JSDoc match those in the function declaration.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param

The following patterns are considered problems:

/**
 * @param Foo
 */
function quux (foo = 'FOO') {

}

/**
 * @arg Foo
 */
function quux (foo = 'FOO') {

}

/**
 * @param Foo
 */
function quux (foo) {

}

/**
 * @param Foo.Bar
 */
function quux (foo) {

}

/**
 * @param foo
 * @param Foo.Bar
 */
function quux (foo) {

}

/**
 * @param foo
 * @param foo.bar
 * @param bar
 */
function quux (bar, foo) {

}

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

}

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

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

}

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

}

/**
 * @param foo
 * @param bar
 */
function quux (foo, bar, baz) {

}

/**
 * @param foo
 * @param foo.foo
 * @param bar
 */
function quux (foo, bar) {

}

check-tag-names

Reports invalid block tag names.

Valid JSDoc 3 Block Tags are:

abstract
access
alias
augments
author
borrows
callback
class
classdesc
constant
constructs
copyright
default
deprecated
description
enum
event
example
exports
external
file
fires
function
global
ignore
implements
inheritdoc
inner
instance
interface
kind
lends
license
listens
member
memberof
mixes
mixin
module
name
namespace
override
param
private
property
protected
public
readonly
requires
returns
see
since
static
summary
this
throws
todo
tutorial
type
typedef
variation
version

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	N/A

The following patterns are considered problems:

/**
 * @Param
 */
function quux () {

}

/**
 * @foo
 */
function quux () {

}

/**
 * @arg foo
 */
function quux (foo) {

}

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

}

The following patterns are not considered problems:

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

}

/**
 * @arg foo
 */
function quux (foo) {

}

check-types

Reports invalid types.

Ensures that case of native types is the same as in this list:

boolean
number
string
Object
Array
Date
RegExp

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	class, constant, enum, member, module, namespace, param, property, returns, throws, type, typedef

The following patterns are considered problems:

/**
 * @param {Number} foo
 */
function quux (foo) {

}

/**
 * @arg {Number} foo
 */
function quux (foo) {

}

The following patterns are not considered problems:

/**
 * @param {number} foo
 * @param {Bar} bar
 * @param {*} baz
 */
function quux (foo, bar, baz) {

}

/**
 * @arg {number} foo
 * @arg {Bar} bar
 * @arg {*} baz
 */
function quux (foo, bar, baz) {

}

newline-after-description

Enforces a consistent padding of the block description.

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

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	N/A

The following patterns are considered problems:

/**
 * Foo.
 *
 * Foo.
 * @foo
 */
function quux () {

}

/**
 * Bar.
 *
 * Bar.
 *
 * @bar
 */
function quux () {

}

The following patterns are not considered problems:

/**
 * Foo.
 */
function quux () {

}

/**
 * Bar.
 */
function quux () {

}

/**
 * Foo.
 *
 * @foo
 */
function quux () {

}

/**
 * Bar.
 * @bar
 */
function quux () {

}

require-description-complete-sentence

Requires that block description and tag description are written in complete sentences, i.e.,

• Description must start with an uppercase alphabetical character.
• Paragraph must start with an uppercase alphabetical character.
• Sentences must end with a period.
• Every line that starts with a lowercase character must be preceded by a line ending the sentence.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param, returns

The following patterns are considered problems:

/**
 * foo.
 */
function quux () {

}

/**
 * Foo.
 *
 * foo.
 */
function quux () {

}

/**
 * Foo
 */
function quux () {

}

/**
 * Foo
 * Bar.
 */
function quux () {

}

/**
 * Foo.
 *
 * @param foo foo.
 */
function quux (foo) {

}

/**
 * Foo.
 *
 * @returns foo.
 */
function quux (foo) {

}

The following patterns are not considered problems:

/**
 * @param foo - Foo.
 */
function quux () {

}

/**
 * Foo.
 */
function quux () {

}

/**
 * Foo.
 * Bar.
 */
function quux () {

}

/**
 * Foo.
 *
 * Bar.
 */
function quux () {

}

/**
 * Foo
 * bar.
 */
function quux () {

}

require-param-description

Requires that @param tag has description value.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param

The following patterns are considered problems:

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

}

/**
 * @arg foo
 */
function quux (foo) {

}

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 * @param foo Foo.
 */
function quux (foo) {

}

require-param

Requires that all function parameters are documented.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param

The following patterns are considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 *
 */
function quux (foo) {

}

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

}

The following patterns are not considered problems:

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

}

/**
 * @arg foo
 */
function quux (foo) {

}

require-param-description

Requires that @param tag has description value.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param

The following patterns are considered problems:

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

}

/**
 * @arg foo
 */
function quux (foo) {

}

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 * @param foo Foo.
 */
function quux (foo) {

}

require-param-type

Requires that @param tag has type value.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	param

The following patterns are considered problems:

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

}

/**
 * @arg foo
 */
function quux (foo) {

}

The following patterns are not considered problems:

/**
 *
 */
function quux (foo) {

}

/**
 * @param {number} foo
 */
function quux (foo) {

}

require-returns-description

Requires that @returns tag has description value.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	returns

The following patterns are considered problems:

/**
 * @returns
 */
function quux (foo) {

}

/**
 * @return
 */
function quux (foo) {

}

The following patterns are not considered problems:

/**
 *
 */
function quux () {

}

/**
 * @returns Foo.
 */
function quux () {

}

require-returns-type

Requires that @returns tag has type value.

Context	ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags	returns

The following patterns are considered problems:

/**
 * @returns
 */
function quux () {

}

/**
 * @returns Foo.
 */
function quux () {

}

/**
 * @return Foo.
 */
function quux () {

}

The following patterns are not considered problems:

/**
 * @returns {number}
 */
function quux () {

}