eslint-plugin-jsdoc
JSDoc linting rules for ESLint.
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 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/no-undefined-types": 1,
"jsdoc/require-description-complete-sentence": 1,
"jsdoc/require-example": 1,
"jsdoc/require-hyphen-before-param-description": 1,
"jsdoc/require-param": 1,
"jsdoc/require-param-description": 1,
"jsdoc/require-param-name": 1,
"jsdoc/require-param-type": 1,
"jsdoc/require-returns-description": 1,
"jsdoc/require-returns-type": 1,
"jsdoc/valid-types": 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"
}
}
}
}
Additional Tag Names
Use settings.jsdoc.additionalTagNames
to configure additional, allowed JSDoc tags. The format of the configuration is as follows:
{
"rules": {},
"settings": {
"jsdoc": {
"additionalTagNames": {
"customTags": ["define", "extends", "record"]
}
}
}
}
Allow @override
Without Accompanying @param
Tags
Use settings.jsdoc.allowOverrideWithoutParam
to indicate whether the @override
tag can be used without accompanying @param
tag(s). The default value is false
. The format of the configuration is as follows:
{
"rules": {},
"settings": {
"jsdoc": {
"allowOverrideWithoutParam": true
}
}
}
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:
function quux (foo = 'FOO') {
}
function quux (foo = 'FOO') {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (bar, foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux (foo) {
}
function quux (foo) {
}
function quux (foo, bar) {
}
function quux (foo, bar, baz) {
}
function quux (foo, bar) {
}
function quux (...args) {
}
function quux ({a, b}) {
}
function quux ({a, b} = {}) {
}
Deconstructing Function Parameter
eslint-plugin-jsdoc
does not validate names of parameters in function deconstruction, e.g.
function quux ({
a,
b
}) {
}
{a, b}
is an ObjectPattern
AST type and does not have a name. Therefore, the associated parameter in JSDoc block can have any name.
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:
function quux () {
}
function quux () {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (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
Why not capital case everything?
Why are boolean
, number
and string
exempt from starting with a capital letter? Let's take string
as an example. In Javascript, everything is an object. The string Object has prototypes for string functions such as .toUpperCase()
.
Fortunately we don't have to write new String()
everywhere in our code. Javascript will automatically wrap string primitives into string Objects when we're applying a string function to a string primitive. This way the memory footprint is a tiny little bit smaller, and the GC has less work to do.
So in a sense, there two types of strings in Javascript; {string}
literals, also called primitives and {String}
Objects. We use the primitives because it's easier to write and uses less memory. {String}
and {string}
are technically both valid, but they are not the same.
new String('lard')
'lard'
new String('lard') === 'lard'
To make things more confusing, there are also object literals and object Objects. But object literals are still static Objects and object Objects are instantiated Objects. So an object primitive is still an object Object.
Basically, for primitives, we want to define the type as a primitive, because that's what we use in 99.9% of cases. For everything else, we use the type rather than the primitive. Otherwise it would all just be {object}
.
In short: It's not about consistency, rather about the 99.9% use case.
type name | typeof | check-types | testcase |
---|
Object | object | Object | ({}) instanceof Object -> true |
Array | object | Array | ([]) instanceof Array -> true |
Date | object | Date | (new Date()) instanceof Date -> true |
RegExp | object | RegExp | (new RegExp(/.+/)) instanceof RegExp -> true |
Boolean | boolean | boolean | (true) instanceof Boolean -> false |
Number | number | number | (41) instanceof Number -> false |
String | string | string | ("test") instanceof String -> false |
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | class , constant , enum , member , module , namespace , param , property , returns , throws , type , typedef |
The following patterns are considered problems:
function quux (foo) {
}
function quux (foo) {
}
function quux (foo, bar, baz) {
}
function quux (foo, bar, baz) {
}
The following patterns are not considered problems:
function quux (foo, bar, baz) {
}
function quux (foo, bar, 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:
function quux () {
}
function quux () {
}
The following patterns are not considered problems:
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
no-undefined-types
Checks that types in jsdoc comments are defined. This can be used to check unimported types.
When enabling this rule, types in jsdoc comments will resolve as used variables, i.e. will not be marked as unused by no-unused-vars
.
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param , returns |
The following patterns are considered problems:
function quux(foo) {
}
The following patterns are not considered problems:
function quux(foo) {
}
class MyClass {}
function quux(foo) {
console.log(foo);
}
quux(0);
const MyType = require('my-library').MyType;
function quux(foo) {
}
import {MyType} from 'my-library';
function quux(foo, bar, baz) {
}
function quux(foo, bar) {
}
function quux(foo) {
}
function quux(foo) {
}
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.
- Paragraphs must start with an uppercase alphabetical character.
- Sentences must end with a period.
- Every line in a paragraph (except the first) which starts with an uppercase character must be preceded by a line ending with a period.
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param , returns |
The following patterns are considered problems:
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function longDescription (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
function quux () {
}
require-example
Requires that all functions have examples.
- All functions must have one or more
@example
tags. - Every example tag must have a non-empty description that explains the method's usage.
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | example |
The following patterns are considered problems:
function quux () {
}
function quux () {
}
The following patterns are not considered problems:
function quux () {
}
function quux () {
}
function quux () {
}
require-hyphen-before-param-description
Requires a hyphen before the @param
description.
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
The following patterns are considered problems:
function quux () {
}
The following patterns are not considered problems:
function quux () {
}
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) {
}
function quux (foo, bar) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux (foo) {
}
function quux (foo) {
}
function quux (foo) {
}
function quux (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:
function quux (foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux (foo) {
}
function quux (foo) {
}
require-param-name
Requires that all function parameters have name.
The @param
tag requires you to specify the name of the parameter you are documenting. You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.
JSDoc
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param |
The following patterns are considered problems:
function quux (foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux (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:
function quux (foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux (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:
function quux (foo) {
}
function quux (foo) {
}
The following patterns are not considered problems:
function quux () {
}
function quux () {
}
require-returns-type
Requires that @returns
tag has type
value.
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | returns |
The following patterns are considered problems:
function quux () {
}
function quux () {
}
function quux () {
}
The following patterns are not considered problems:
function quux () {
}
valid-types
Requires all types to be valid JSDoc or Closure compiler types without syntax errors.
| |
---|
Context | ArrowFunctionExpression , FunctionDeclaration , FunctionExpression |
Tags | param , returns |
The following patterns are considered problems:
function quux() {
}
The following patterns are not considered problems:
function quux() {
}
function quux() {
}
function quux() {
}