Security News
Cloudflare Adds Security.txt Setup Wizard
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
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.
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.
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-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
}
}
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
RegExp
The 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 () {
}
FAQs
JSDoc linting rules for ESLint.
The npm package eslint-plugin-jsdoc receives a total of 1,799,699 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
Cloudflare has launched a setup wizard allowing users to easily create and manage a security.txt file for vulnerability disclosure on their websites.
Security News
The Socket Research team breaks down a malicious npm package targeting the legitimate DOMPurify library. It uses obfuscated code to hide that it is exfiltrating browser and crypto wallet data.
Security News
ENISA’s 2024 report highlights the EU’s top cybersecurity threats, including rising DDoS attacks, ransomware, supply chain vulnerabilities, and weaponized AI.