eslint-plugin-jsdoc
Advanced tools
Package description
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.
Readme
JSDoc linting rules for ESLint.
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
import jsdoc from 'eslint-plugin-jsdoc';
const config = [
// configuration included in plugin
jsdoc.configs['flat/recommended'],
// other configuration objects...
{
files: ['**/*.js'],
plugins: {
jsdoc,
},
rules: {
'jsdoc/require-description': 'warn'
}
}
];
export default config;
eslintrcAdd plugins section to .eslintrc.*
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-access": 1, // Recommended
"jsdoc/check-alignment": 1, // Recommended
"jsdoc/check-examples": 1,
"jsdoc/check-indentation": 1,
"jsdoc/check-line-alignment": 1,
"jsdoc/check-param-names": 1, // Recommended
"jsdoc/check-property-names": 1, // Recommended
"jsdoc/check-syntax": 1,
"jsdoc/check-tag-names": 1, // Recommended
"jsdoc/check-types": 1, // Recommended
"jsdoc/check-values": 1, // Recommended
"jsdoc/empty-tags": 1, // Recommended
"jsdoc/implements-on-classes": 1, // Recommended
"jsdoc/informative-docs": 1,
"jsdoc/match-description": 1,
"jsdoc/multiline-blocks": 1, // Recommended
"jsdoc/no-bad-blocks": 1,
"jsdoc/no-blank-block-descriptions": 1,
"jsdoc/no-defaults": 1,
"jsdoc/no-missing-syntax": 1,
"jsdoc/no-multi-asterisks": 1, // Recommended
"jsdoc/no-restricted-syntax": 1,
"jsdoc/no-types": 1,
"jsdoc/no-undefined-types": 1, // Recommended
"jsdoc/require-asterisk-prefix": 1,
"jsdoc/require-description": 1,
"jsdoc/require-description-complete-sentence": 1,
"jsdoc/require-example": 1,
"jsdoc/require-file-overview": 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-property": 1, // Recommended
"jsdoc/require-property-description": 1, // Recommended
"jsdoc/require-property-name": 1, // Recommended
"jsdoc/require-property-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/require-throws": 1,
"jsdoc/require-yields": 1, // Recommended
"jsdoc/require-yields-check": 1, // Recommended
"jsdoc/sort-tags": 1,
"jsdoc/tag-lines": 1, // Recommended
"jsdoc/valid-types": 1 // Recommended
}
}
Or you can simply add the following to .eslintrc.*, which enables the rules commented above as "recommended":
{
"extends": ["plugin:jsdoc/recommended"]
}
You can then selectively add to or override the recommended rules.
Alternatively, if you wish to have all linting issues reported as failing errors, you may use the "recommended-error" config:
{
"extends": ["plugin:jsdoc/recommended-error"]
}
If you plan to use TypeScript syntax (and not just "typescript"
mode to indicate the JSDoc flavor is TypeScript), you can use:
{
"extends": ["plugin:jsdoc/recommended-typescript"]
}
...or to report with failing errors instead of mere warnings:
{
"extends": ["plugin:jsdoc/recommended-typescript-error"]
}
If you are not using TypeScript syntax (your source files are still .js files)
but you are using the TypeScript flavor within JSDoc (i.e., the default
"typescript" mode in eslint-plugin-jsdoc) and you are perhaps using
allowJs and checkJs options of TypeScript's tsconfig.json), you may
use:
{
"extends": ["plugin:jsdoc/recommended-typescript-flavor"]
}
...or to report with failing errors instead of mere warnings:
{
"extends": ["plugin:jsdoc/recommended-typescript-flavor-error"]
}
Rules may, as per the ESLint user guide, have their own individual options. In eslint-plugin-jsdoc, a few options,
such as, exemptedBy and contexts, may be used across different rules.
eslint-plugin-jsdoc options, if present, are generally in the form of an
object supplied as the second argument in an array after the error level
(any exceptions to this format are explained within that rule's docs).
// `.eslintrc.js`
{
rules: {
'jsdoc/require-example': [
// The Error level should be `error`, `warn`, or `off` (or 2, 1, or 0)
'error',
// The options vary by rule, but are generally added to an options
// object as follows:
{
checkConstructors: true,
exemptedBy: ['type']
}
]
}
}
See Settings.
See Advanced.
Problems reported by rules which have a wrench :wrench: below can be fixed automatically by running ESLint on the command line with --fix option.
Note that a number of fixable rules have an enableFixer option which can
be set to false to disable the fixer (or in the case of check-param-names,
check-property-names, and no-blank-blocks, set to true to enable a
non-default-recommended fixer).
| recommended | fixable | rule | description |
|---|---|---|---|
| :heavy_check_mark: | check-access | Enforces valid @access tags | |
| :heavy_check_mark: | :wrench: | check-alignment | Enforces alignment of JSDoc block asterisks |
| check-examples | Linting of JavaScript within @example | ||
| check-indentation | Checks for invalid padding inside JSDoc blocks | ||
| :wrench: | check-line-alignment | Reports invalid alignment of JSDoc block lines. | |
| :heavy_check_mark: | :wrench: | check-param-names | Checks for dupe @param names, that nested param names have roots, and that parameter names in function declarations match jsdoc param names. |
| :heavy_check_mark: | :wrench: | check-property-names | Checks for dupe @property names, that nested property names have roots |
| check-syntax | Reports use against current mode (currently only prohibits Closure-specific syntax) | ||
| :heavy_check_mark: | :wrench: | check-tag-names | Reports invalid jsdoc (block) tag names |
| :heavy_check_mark: | :wrench: | check-types | Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements) |
| :heavy_check_mark: | check-values | Checks for expected content within some miscellaneous tags (@version, @since, @license, @author) | |
| :heavy_check_mark: | :wrench: | empty-tags | Checks tags that are expected to be empty (e.g., @abstract or @async), reporting if they have content |
| :heavy_check_mark: | implements-on-classes | Prohibits use of @implements on non-constructor functions (to enforce the tag only being used on classes/constructors) | |
| informative-docs | Reports on JSDoc texts that serve only to restate their attached name. | ||
| match-description | Defines customizable regular expression rules for your tag descriptions | ||
| :wrench: | match-name | Reports the name portion of a JSDoc tag if matching or not matching a given regular expression | |
| :heavy_check_mark: | :wrench: | multiline-blocks | Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks |
| :wrench: | no-bad-blocks | This rule checks for multi-line-style comments which fail to meet the criteria of a jsdoc block | |
| :wrench: | no-blank-block-descriptions | If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description. | |
| :wrench: | no-blank-blocks | Reports and optionally removes blocks with whitespace only | |
| :heavy_check_mark: | :wrench: | no-defaults | This rule reports defaults being used on the relevant portion of @param or @default |
| no-missing-syntax | This rule lets you report if certain always expected comment structures are missing. | ||
| :heavy_check_mark: | :wrench: | no-multi-asterisks | Prevents use of multiple asterisks at the beginning of lines |
| no-restricted-syntax | Reports when certain comment structures are present | ||
| On in TS | :wrench: | no-types | Prohibits types on @param or @returns (redundant with TypeScript) |
| :heavy_check_mark: (off in TS and TS flavor) | no-undefined-types | Besides some expected built-in types, prohibits any types not specified as globals or within @typedef | |
| :wrench: | require-asterisk-prefix | Requires that each JSDoc line starts with an * | |
| require-description | Requires that all functions (and potentially other contexts) have a description. | ||
| :wrench: | require-description-complete-sentence | Requires that block description, explicit @description, and @param/@returns tag descriptions are written in complete sentences | |
| :wrench: | require-example | Requires that all functions (and potentially other contexts) have examples. | |
| require-file-overview | By default, requires a single @file tag at the beginning of each linted file | ||
| :wrench: | require-hyphen-before-param-description | Requires a hyphen before @param descriptions (and optionally before @property descriptions) | |
| :heavy_check_mark: | :wrench: | require-jsdoc | Checks for presence of jsdoc comments, on functions and potentially other contexts (optionally limited to exports). |
| :heavy_check_mark: | :wrench: | require-param | Requires that all function parameters are documented with a @param tag. |
| :heavy_check_mark: | require-param-description | Requires that each @param tag has a description value. | |
| :heavy_check_mark: | require-param-name | Requires that all @param tags have names. | |
| :heavy_check_mark: (off in TS) | require-param-type | Requires that each @param tag has a type value (within curly brackets). | |
| :heavy_check_mark: | :wrench: | require-property | Requires that all @typedef and @namespace tags have @property tags when their type is a plain object, Object, or PlainObject. |
| :heavy_check_mark: | require-property-description | Requires that each @property tag has a description value. | |
| :heavy_check_mark: | require-property-name | Requires that all @property tags have names. | |
| :heavy_check_mark: (off in TS) | require-property-type | Requires that each @property tag has a type value (within curly brackets). | |
| :heavy_check_mark: | require-returns | Requires that return statements are documented. | |
| :heavy_check_mark: | require-returns-check | Requires a return statement be present in a function body if a @returns tag is specified in the jsdoc comment block (and reports if multiple @returns tags are present). | |
| :heavy_check_mark: | require-returns-description | Requires that the @returns tag has a description value (not including void/undefined type returns). | |
| :heavy_check_mark: (off in TS) | require-returns-type | Requires that @returns tag has a type value (in curly brackets). | |
| require-throws | Requires that throw statements are documented | ||
| :heavy_check_mark: | require-yields | Requires that yields are documented | |
| :heavy_check_mark: | require-yields-check | Ensures that if a @yields is present that a yield (or yield with a value) is present in the function body (or that if a @next is present that there is a yield with a return value present) | |
| sort-tags | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups | ||
| :heavy_check_mark: | :wrench: | tag-lines | Enforces lines (or no lines) between tags |
| :wrench: | text-escaping | This rule can auto-escape certain characters that are input within block and tag descriptions | |
| :heavy_check_mark: | valid-types | Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings) |
FAQs
JSDoc linting rules for ESLint.
The npm package eslint-plugin-jsdoc receives a total of 1,587,136 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
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.
Security News
GitHub is susceptible to a CDN flaw that allows attackers to host malware on any public repository.
Security News
At Node Congress, Socket CEO Feross Aboukhadijeh uncovers the darker aspects of open source, where applications that rely heavily on third-party dependencies can be exploited in supply chain attacks.