Skip to content

jscharett/eslint-plugin-jsdoc

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

eslint-plugin-jsdoc

NPM version Travis build status js-canonical-style

JSDoc linting rules for ESLint.

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-example N/A
require-hyphen-before-param-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-example": 1,
        "jsdoc/require-hyphen-before-param-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"
            }
        }
    }
}

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

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') {

}
// Message: Expected @param names to be "foo". Got "Foo".

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

}
// Message: Expected @arg names to be "foo". Got "Foo".

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

}
// Message: Expected @param names to be "foo". Got "Foo".

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

}
// Message: @param path declaration ("Foo.Bar") appears before any real parameter.

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

}
// Message: @param path declaration ("Foo.Bar") root node name ("Foo") does not match previous real parameter name ("foo").

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

}
// Message: Expected @param names to be "bar, foo". Got "foo, bar".

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

}
// Message: @param "bar" does not match an existing function parameter.

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) {

}

/**
 * @param args
 */
function quux (...args) {

}

/**
 * @param foo
 */
function quux ({a, b}) {

}

/**
 * @param foo
 */
function quux ({a, b} = {}) {

}

Deconstructing Function Parameter

eslint-plugin-jsdoc does not validate names of parameters in function deconstruction, e.g.

/**
 * @param foo
 */
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:

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

}
// Message: Invalid JSDoc tag name "Param".

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

}
// Message: Invalid JSDoc tag name "foo".

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

}
// Message: Invalid JSDoc tag (preference). Replace "arg" JSDoc tag with "param".

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

}
// Message: Invalid JSDoc tag (preference). Replace "param" JSDoc tag with "arg".

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

}
// Message: Invalid JSDoc tag name "bar".

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

}
// Message: Invalid JSDoc tag name "baz".

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

}
// Message: Invalid JSDoc tag name "baz".

The following patterns are not considered problems:

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

}

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

}

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

}

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

}

/** 
 * @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
 */
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') // String {0: "l", 1: "a", 2: "r", 3: "d", length: 4}
'lard' // "lard"
new String('lard') === 'lard' // false

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:

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

}
// Message: Invalid JSDoc @param "foo" type "Number".

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

}
// Message: Invalid JSDoc @arg "foo" type "Number".

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 () {

}
// Options: ["always"]
// Message: There must be a newline after the description of the JSDoc block.

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

}
// Options: ["never"]
// Message: There must be no newline after the description of the JSDoc block.

The following patterns are not considered problems:

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

}
// Options: ["always"]

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

}
// Options: ["never"]

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

}
// Options: ["always"]

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

}
// Options: ["never"]

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 () {

}
// Message: Description must start with an uppercase character.

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

}
// Message: Paragraph must start with an uppercase character.

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

}
// Message: Sentence must end with a period.

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

}
// Message: A line of text is started with an uppercase character, but preceding line does not end the sentence.

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

}
// Message: Description must start with an uppercase character.

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

}
// Message: Description must start with an uppercase character.

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 () {

}

/**
 * @returns Foo bar.
 */
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 () {

}
// Message: Missing JSDoc @example declaration.

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

}
// Message: Missing JSDoc @example description.

The following patterns are not considered problems:

/**
 * @example
 * // arbitrary example content
 */
function quux () {

}

/**
 * @example
 * quux(); // does something useful
 */
function quux () {

}

/**
 * @example <caption>Valid usage</caption>
 * quux(); // does something useful
 *
 * @example <caption>Invalid usage</caption>
 * quux('random unwanted arg'); // results in an error
 */
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:

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

}
// Message: There must be a hyphen before @param description.

The following patterns are not considered problems:

/**
 * @param foo - Foo.
 */
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) {

}
// Message: Missing JSDoc @param "foo" declaration.

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

}
// Message: Missing JSDoc @arg "foo" declaration.

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

}
// Message: Missing JSDoc @param "bar" declaration.

The following patterns are not considered problems:

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

}

/**
 * @inheritdoc
 */
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) {

}
// Message: Missing JSDoc @param "foo" description.

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

}
// Message: Missing JSDoc @arg "foo" description.

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) {

}
// Message: Missing JSDoc @param "foo" type.

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

}
// Message: Missing JSDoc @arg "foo" type.

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) {

}
// Message: Missing JSDoc @returns description.

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

}
// Message: Missing JSDoc @return description.

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 () {

}
// Message: Missing JSDoc @returns type.

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

}
// Message: Missing JSDoc @returns type.

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

}
// Message: Missing JSDoc @return type.

The following patterns are not considered problems:

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

}

About

JSDoc specific linting rules for ESLint.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%