eslint-plugin-jsdoc
Advanced tools
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.
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}!`;
}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.
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 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.
JSDoc specific linting rules for ESLint.
This table maps the rules between eslint-plugin-jsdoc and jscs-jsdoc.
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
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-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
}
}
check-param-namesEnsures that parameters 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
* @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-namesReports 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
The following patterns are considered problems:
/**
* @Param
*/
function quux () {
}
/**
* @foo
*/
function quux () {
}
The following patterns are not considered problems:
/**
* @param {number} foo
*/
function quux (foo) {
}
check-typesReports invalid types.
Ensures that case of native types is the same as in this list:
boolean
number
string
Object
Array
Date
RegExp
Affected tags:
class
constant
enum
member
module
namespace
param
property
returns
throws
type
typede
The following patterns are considered problems:
/**
* @param {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) {
}
newline-after-descriptionEnforces 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".
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-param-descriptionRequires that @param tag has description value.
The following patterns are considered problems:
/**
* @param foo
*/
function quux (foo) {
}
The following patterns are not considered problems:
/**
*
*/
function quux (foo) {
}
/**
* @param foo Foo.
*/
function quux (foo) {
}
require-paramRequires that all function parameters are documented.
The following patterns are considered problems:
/**
*
*/
function quux (foo) {
}
/**
* @param foo
*/
function quux (foo, bar) {
}
The following patterns are not considered problems:
/**
* @param foo
*/
function quux (foo) {
}
require-param-descriptionRequires that @param tag has description value.
The following patterns are considered problems:
/**
* @param foo
*/
function quux (foo) {
}
The following patterns are not considered problems:
/**
*
*/
function quux (foo) {
}
/**
* @param foo Foo.
*/
function quux (foo) {
}
require-param-typeRequires that @param tag has type value.
The following patterns are considered problems:
/**
* @param foo
*/
function quux (foo) {
}
The following patterns are not considered problems:
/**
*
*/
function quux (foo) {
}
/**
* @param {number} foo
*/
function quux (foo) {
}
require-returns-descriptionRequires that @returns tag has description value.
The following patterns are considered problems:
/**
* @returns
*/
function quux (foo) {
}
The following patterns are not considered problems:
/**
*
*/
function quux () {
}
/**
* @returns Foo.
*/
function quux () {
}
require-returns-typeRequires that @returns tag has type value.
The following patterns are considered problems:
/**
* @returns
*/
function quux () {
}
/**
* @returns Foo.
*/
function quux () {
}
The following patterns are not considered problems:
/**
* @returns {number}
*/
function quux () {
}
FAQs
JSDoc linting rules for ESLint.
The npm package eslint-plugin-jsdoc receives a total of 1,029,539 weekly downloads. As such, eslint-plugin-jsdoc popularity was classified as popular.
We found that eslint-plugin-jsdoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.