Google Git
Sign in
chromium / devtools / devtools-frontend.git / HEAD / . / node_modules / eslint-plugin-jsdoc / README.md
blob: 96652fff46d4df1b70d718f87fa3eb693bce0129 [file] [log] [blame] [view]
<a name="user-content-eslint-plugin-jsdoc"></a>
<a name="eslint-plugin-jsdoc"></a>
# eslint-plugin-jsdoc
[![NPM version](https://img.shields.io/npm/v/eslint-plugin-jsdoc.svg?style=flat-square)](https://www.npmjs.org/package/eslint-plugin-jsdoc)
[![Travis build status](https://img.shields.io/travis/gajus/eslint-plugin-jsdoc/master.svg?style=flat-square)](https://travis-ci.org/gajus/eslint-plugin-jsdoc)
[![js-canonical-style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
[![Discord Chat](https://img.shields.io/badge/chat-on%20disord-green.svg?logo=discord)](https://discord.gg/kFFy3nc)
JSDoc linting rules for ESLint.
* [eslint-plugin-jsdoc](#user-content-eslint-plugin-jsdoc)
* [Installation](#user-content-eslint-plugin-jsdoc-installation)
* [Configuration](#user-content-eslint-plugin-jsdoc-configuration)
* [Flat config (procedural)](#user-content-eslint-plugin-jsdoc-configuration-flat-config-procedural)
* [Flat config (declarative)](#user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative)
* [`eslintrc`](#user-content-eslint-plugin-jsdoc-configuration-eslintrc)
* [Options](#user-content-eslint-plugin-jsdoc-options)
* [Settings](#user-content-eslint-plugin-jsdoc-settings)
* [Advanced](#user-content-eslint-plugin-jsdoc-advanced)
* [Processors](#user-content-eslint-plugin-jsdoc-processors)
* [Rules](#user-content-eslint-plugin-jsdoc-rules)
<a name="user-content-eslint-plugin-jsdoc-installation"></a>
<a name="eslint-plugin-jsdoc-installation"></a>
## Installation
Install [ESLint](https://www.github.com/eslint/eslint) either locally or
globally.
```sh
npm install --save-dev eslint
```
If you have installed `ESLint` globally, you have to install JSDoc plugin
globally too. Otherwise, install it locally.
```sh
npm install --save-dev eslint-plugin-jsdoc
```
<a name="user-content-eslint-plugin-jsdoc-configuration"></a>
<a name="eslint-plugin-jsdoc-configuration"></a>
## Configuration
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-procedural"></a>
<a name="eslint-plugin-jsdoc-configuration-flat-config-procedural"></a>
### Flat config (procedural)
This is the currently recommended approach for all flat configs (besides the
array-based `examples`, `default-expressions`, and
`examples-and-default-expressions` configs).
```js
import {jsdoc} from 'eslint-plugin-jsdoc';
export default [
jsdoc({
config: 'flat/recommended',
})
];
```
Or with TypeScript-aware extra rules and/or settings supplied:
```js
import {jsdoc} from 'eslint-plugin-jsdoc';
export default [
jsdoc({
config: 'flat/recommended',
rules: {
'jsdoc/check-values': [
'error',
{
allowedLicenses: [
'MIT', 'ISC',
],
},
],
},
// Uncomment this if you wish your `settings` to overwrite the config's own settings;
// otherwise, the default behavior is to merge recursively
// mergeSettings: false,
settings: {
// Do not add a `jsdoc` child object here as you would for regular ESLint `settings`
structuredTags: {
see: {
name: 'namepath-referencing',
required: [
'name',
],
},
},
/*
// Since the recommended config has been chosen, the above settings will
// be merged by default with the following (which are tags that are
// being allowed and requiring a type):
structuredTags: {
next: {
required: [
'type',
],
},
},
*/
}
})
];
```
A `plugins` property can also be supplied to merge with the resulting `jsdoc` plugin.
Other config properties such as `files`, `ignores`, etc. are also copied over,
though noting that if the specified config produces an array, they will not
currently function.
There is also a `extraRuleDefinitions.forbid` option, the details of which are
explained in the [Advanced](./docs/advanced.md#forbidding-structures) docs
(under creating your own rules and forbidding structures).
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
### Flat config (declarative)
```js
import jsdoc from 'eslint-plugin-jsdoc';
const config = [
// configuration included in plugin
jsdoc.configs['flat/recommended'],
// other configuration objects...
{
files: ['**/*.js'],
// `plugins` here is not necessary if including the above config
plugins: {
jsdoc,
},
rules: {
'jsdoc/require-description': 'warn'
}
}
];
export default config;
```
The general starting rulesets you can extend from in flat config are:
- `jsdoc.configs['flat/recommended']`: Recommended starting rules for enforcing proper tag values, that common tags exist, and that tags are formatted and styled consistently
- `jsdoc.configs['flat/recommended-error']`: The same, reporting with failing errors instead of mere warnings
- `jsdoc.configs['flat/recommended-typescript']`: A similar recommended starting list, adjusted for projects using TypeScript syntax (and not just the "typescript" `mode` setting)
- `jsdoc.configs['flat/recommended-typescript-error']`: The same, reporting with failing errors instead of mere warnings
- `jsdoc.configs['flat/recommended-typescript-flavor']`: A similar recommended starting list, adjusted for projects using JavaScript syntax (source files that are still `.js`) but using TypeScript flavor within JSDoc (i.e., the default "typescript" `mode` in `eslint-plugin-jsdoc`)
- `jsdoc.configs['flat/recommended-typescript-flavor-error']`: The same, reporting with failing errors instead of mere warnings
- `jsdoc.configs['flat/recommended-mixed']`: A combination of `flat/recommended-typescript-flavor` and `flat/recommended-typescript` with automatic assignment of subconfig based on file extension (`**/*.{js,jsx,cjs,mjs}` and `**/*.{ts,tsx,cts,mts}`, respectively)
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
#### Granular Flat Configs
There also exist several more granular, standalone TypeScript rulesets you can extend from.
These each only enable mostly or only rules from the recommended starting rules:
- **Contents**: rules that check names and descriptions
- `jsdoc.configs['flat/contents-typescript']`: for TypeScript files, with reports set to warn
- `jsdoc.configs['flat/contents-typescript-error']`: for TypeScript files, with reports set to error
- `jsdoc.configs['flat/contents-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
- `jsdoc.configs['flat/contents-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
- **Logical**: rules that enforce proper tag values
- `jsdoc.configs['flat/logical-typescript']`: for TypeScript files, with reports set to warn
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
- `jsdoc.configs['flat/logical-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
- **Requirements**: rules that enforce tags exist or have or don't have types
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
- `jsdoc.configs['flat/requirements-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
- **Stylistic**: rules that enforce clear, consistent tag formatting and styles
- `jsdoc.configs['flat/stylistic-typescript']`: for TypeScript files, with reports set to warn
- `jsdoc.configs['flat/stylistic-typescript-error']`: for TypeScript files, with reports set to error
- `jsdoc.configs['flat/stylistic-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
- `jsdoc.configs['flat/stylistic-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
For example, to enforce only that any JSDoc tags and their contents are valid and styled consistently in TypeScript files, without enforcing that tags must always exist:
```js
import jsdoc from 'eslint-plugin-jsdoc';
export default [
jsdoc.configs['flat/contents-typescript-error'],
jsdoc.configs['flat/logical-typescript-error'],
jsdoc.configs['flat/stylistic-typescript-error'],
];
```
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
##### Why certain rules were excluded from the granular configs
A few rules were left out of the granular configs. Here is why:
Rules which might have been added to `required`:
- [`require-throws`](./docs/rules/require-throws.md#readme) - Since this can't enforce all cases, some may not wish this rule enforced.
- [`require-file-overview`](./docs/rules/require-file-overview.md#readme) - Too demanding for all projects
- [`convert-to-jsdoc-comments`](./docs/rules/convert-to-jsdoc-comments.md#readme) - Overly aggressive for some projects
Rules which might have been added to `logical`:
- [`no-missing-syntax`](./docs/rules/no-missing-syntax.md#readme) - Has no default options.
- [`no-restricted-syntax`](./docs/rules/no-restricted-syntax.md#readme) - Has no default options.
Rules which might have been added to `contents`:
- [`match-name`](./docs/rules/match-name.md#readme) - Has no default options.
- [`require-description`](./docs/rules/require-description.md#readme) - Too demanding for all projects
- [`require-description-complete-sentence`](./docs/rules/require-description-complete-sentence.md#readme) - Too demanding for all projects
Rules which might have been added to `stylistic`:
- [`check-indentation`](./docs/rules/check-indentation.md#readme) - May not be desired by all projects
- [`sort-tags`](./docs/rules/sort-tags.md#readme) - Too project-specific
<a name="user-content-eslint-plugin-jsdoc-configuration-eslintrc"></a>
<a name="eslint-plugin-jsdoc-configuration-eslintrc"></a>
### <code>eslintrc</code>
Add `plugins` section to [.eslintrc.*](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)
and specify `eslint-plugin-jsdoc` as a plugin.
```json
{
"plugins": [
"jsdoc"
]
}
```
Finally, enable all of the rules that you would like to use.
```javascript
{
"rules": {
"jsdoc/check-access": 1, // Recommended
"jsdoc/check-alignment": 1, // Recommended
// "jsdoc/check-examples": 1, // Deprecated and not for ESLint >= 8
"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-template-names": 1,
"jsdoc/check-types": 1, // Recommended
"jsdoc/check-values": 1, // Recommended
"jsdoc/convert-to-jsdoc-comments": 1,
"jsdoc/empty-tags": 1, // Recommended
"jsdoc/implements-on-classes": 1, // Recommended
"jsdoc/imports-as-dependencies": 1,
"jsdoc/informative-docs": 1,
"jsdoc/lines-before-block": 1,
"jsdoc/match-description": 1,
"jsdoc/match-name": 1,
"jsdoc/multiline-blocks": 1, // Recommended
"jsdoc/no-bad-blocks": 1,
"jsdoc/no-blank-block-descriptions": 1,
"jsdoc/no-defaults": 1, // Recommended
"jsdoc/no-missing-syntax": 1,
"jsdoc/no-multi-asterisks": 1, // Recommended
"jsdoc/no-restricted-syntax": 1,
"jsdoc/no-types": 1, // Recommended for TS configs
"jsdoc/no-undefined-types": 1, // Recommended for non-TS configs
"jsdoc/rejct-any-type": 1, // Recommended
"jsdoc/reject-function-type": 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-next-description": 1,
"jsdoc/require-next-type": 1, // Recommended
"jsdoc/require-param-description": 1, // Recommended
"jsdoc/require-param-name": 1, // Recommended
"jsdoc/require-param-type": 1, // Recommended in non-TS configs
"jsdoc/require-param": 1, // Recommended
"jsdoc/require-property-description": 1, // Recommended
"jsdoc/require-property-name": 1, // Recommended
"jsdoc/require-property-type": 1, // Recommended in non-TS configs
"jsdoc/require-property": 1, // Recommended
"jsdoc/require-returns-check": 1, // Recommended
"jsdoc/require-returns-description": 1, // Recommended
"jsdoc/require-returns-type": 1, // Recommended in non-TS configs
"jsdoc/require-returns": 1, // Recommended
"jsdoc/require-template": 1,
"jsdoc/require-template-description": 1,
"jsdoc/require-throws": 1,
"jsdoc/require-throws-description": 1,
"jsdoc/require-throws-type": 1, // Recommended
"jsdoc/require-yields-check": 1, // Recommended
"jsdoc/require-yields-description": 1,
"jsdoc/require-yields-type": 1, // Recommended
"jsdoc/require-yields": 1, // Recommended
"jsdoc/sort-tags": 1,
"jsdoc/tag-lines": 1, // Recommended
"jsdoc/text-escaping": 1,
"jsdoc/type-formatting": 1,
"jsdoc/valid-types": 1 // Recommended
}
}
```
Or you can simply add the following to [.eslintrc.*](https://eslint.org/docs/user-guide/configuring#configuration-file-formats),
which enables the rules commented above as "recommended":
```json
{
"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:
```json
{
"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:
```json
{
"extends": ["plugin:jsdoc/recommended-typescript"]
}
```
...or to report with failing errors instead of mere warnings:
```json
{
"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:
```json
{
"extends": ["plugin:jsdoc/recommended-typescript-flavor"]
}
```
...or to report with failing errors instead of mere warnings:
```json
{
"extends": ["plugin:jsdoc/recommended-typescript-flavor-error"]
}
```
<a name="user-content-eslint-plugin-jsdoc-options"></a>
<a name="eslint-plugin-jsdoc-options"></a>
## Options
Rules may, as per the [ESLint user guide](https://eslint.org/docs/user-guide/configuring), 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).
```js
// `.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']
}
]
}
}
```
<a name="user-content-eslint-plugin-jsdoc-settings"></a>
<a name="eslint-plugin-jsdoc-settings"></a>
## Settings
See [Settings](./docs/settings.md#readme).
<a name="user-content-eslint-plugin-jsdoc-advanced"></a>
<a name="eslint-plugin-jsdoc-advanced"></a>
## Advanced
See [Advanced](./docs/advanced.md#readme).
<a name="user-content-eslint-plugin-jsdoc-processors"></a>
<a name="eslint-plugin-jsdoc-processors"></a>
## Processors
See our `@example` and other item [processors](./docs/processors.md#readme).
<a name="user-content-eslint-plugin-jsdoc-rules"></a>
<a name="eslint-plugin-jsdoc-rules"></a>
## Rules
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](./docs/rules/check-access.md#readme) | Checks that `@access` tags have a valid value. |
|:heavy_check_mark:|:wrench:| [check-alignment](./docs/rules/check-alignment.md#readme) | Reports invalid alignment of JSDoc block asterisks. |
||| [check-examples](./docs/rules/check-examples.md#readme) | @deprecated - Use `getJsdocProcessorPlugin` processor; ensures that (JavaScript) samples within `@example` tags adhere to ESLint rules. |
||| [check-indentation](./docs/rules/check-indentation.md#readme) | Reports invalid padding inside JSDoc blocks. |
||:wrench:| [check-line-alignment](./docs/rules/check-line-alignment.md#readme) | Reports invalid alignment of JSDoc block lines. |
|:heavy_check_mark:|:wrench:| [check-param-names](./docs/rules/check-param-names.md#readme) | 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](./docs/rules/check-property-names.md#readme) | Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots. |
||| [check-syntax](./docs/rules/check-syntax.md#readme) | Reports against syntax not valid for the mode (e.g., Google Closure Compiler in non-Closure mode). |
|:heavy_check_mark:|:wrench:| [check-tag-names](./docs/rules/check-tag-names.md#readme) | Reports invalid block tag names. |
||| [check-template-names](./docs/rules/check-template-names.md#readme) | Checks that any `@template` names are actually used in the connected `@typedef` or type alias. |
|:heavy_check_mark:|:wrench:| [check-types](./docs/rules/check-types.md#readme) | Reports types deemed invalid (customizable and with defaults, for preventing and/or recommending replacements). |
|:heavy_check_mark:|| [check-values](./docs/rules/check-values.md#readme) | This rule checks the values for a handful of tags: `@version`, `@since`, `@license` and `@author`. |
||:wrench:| [convert-to-jsdoc-comments](./docs/rules/convert-to-jsdoc-comments.md#readme) | Converts non-JSDoc comments preceding or following nodes into JSDoc ones |
|:heavy_check_mark:|:wrench:| [empty-tags](./docs/rules/empty-tags.md#readme) | Checks tags that are expected to be empty (e.g., `@abstract` or `@async`), reporting if they have content |
|:heavy_check_mark:|| [implements-on-classes](./docs/rules/implements-on-classes.md#readme) | Prohibits use of `@implements` on non-constructor functions (to enforce the tag only being used on classes/constructors). |
||| [imports-as-dependencies](./docs/rules/imports-as-dependencies.md#readme) | Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies` |
||| [informative-docs](./docs/rules/informative-docs.md#readme) | This rule reports doc comments that only restate their attached name. |
||:wrench:| [lines-before-block](./docs/rules/lines-before-block.md#readme) | Enforces minimum number of newlines before JSDoc comment blocks |
||| [match-description](./docs/rules/match-description.md#readme) | Enforces a regular expression pattern on descriptions. |
||:wrench:| [match-name](./docs/rules/match-name.md#readme) | Reports the name portion of a JSDoc tag if matching or not matching a given regular expression. |
|:heavy_check_mark:|:wrench:| [multiline-blocks](./docs/rules/multiline-blocks.md#readme) | Controls how and whether JSDoc blocks can be expressed as single or multiple line blocks. |
||:wrench:| [no-bad-blocks](./docs/rules/no-bad-blocks.md#readme) | This rule checks for multi-line-style comments which fail to meet the criteria of a JSDoc block. |
||:wrench:| [no-blank-block-descriptions](./docs/rules/no-blank-block-descriptions.md#readme) | 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](./docs/rules/no-blank-blocks.md#readme) | Removes empty blocks with nothing but possibly line breaks |
|:heavy_check_mark:|:wrench:| [no-defaults](./docs/rules/no-defaults.md#readme) | This rule reports defaults being used on the relevant portion of `@param` or `@default`. |
||| [no-missing-syntax](./docs/rules/no-missing-syntax.md#readme) | Reports when certain comment structures are always expected. |
|:heavy_check_mark:|:wrench:| [no-multi-asterisks](./docs/rules/no-multi-asterisks.md#readme) | Prevents use of multiple asterisks at the beginning of lines. |
||| [no-restricted-syntax](./docs/rules/no-restricted-syntax.md#readme) | Reports when certain comment structures are present. |
|On in TS; Off in TS flavor|:wrench:| [no-types](./docs/rules/no-types.md#readme) | This rule reports types being used on `@param` or `@returns` (redundant with TypeScript). |
|:heavy_check_mark: (Off in TS; Off in TS flavor)|| [no-undefined-types](./docs/rules/no-undefined-types.md#readme) | Besides some expected built-in types, prohibits any types not specified as globals or within `@typedef`. |
||:wrench:| [prefer-import-tag](./docs/rules/prefer-import-tag.md#readme) | Prefer `@import` tags to inline `import()` statements. |
|:heavy_check_mark:|| [reject-any-type](./docs/rules/reject-any-type.md#readme) | Reports use of `any` or `*` type |
|:heavy_check_mark:|| [reject-function-type](./docs/rules/reject-function-type.md#readme) | Reports use of `Function` type |
||:wrench:| [require-asterisk-prefix](./docs/rules/require-asterisk-prefix.md#readme) | Requires that each JSDoc line starts with an `*`. |
||| [require-description](./docs/rules/require-description.md#readme) | Requires that all functions (and potentially other contexts) have a description. |
||:wrench:| [require-description-complete-sentence](./docs/rules/require-description-complete-sentence.md#readme) | Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences. |
||:wrench:| [require-example](./docs/rules/require-example.md#readme) | Requires that all functions (and potentially other contexts) have examples. |
||| [require-file-overview](./docs/rules/require-file-overview.md#readme) | Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file. |
||:wrench:| [require-hyphen-before-param-description](./docs/rules/require-hyphen-before-param-description.md#readme) | Requires a hyphen before the `@param` description (and optionally before `@property` descriptions). |
|:heavy_check_mark:|:wrench:| [require-jsdoc](./docs/rules/require-jsdoc.md#readme) | Checks for presence of JSDoc comments, on functions and potentially other contexts (optionally limited to exports). |
||| [require-next-description](./docs/rules/require-next-description.md#readme) | Requires a description for `@next` tags |
|:heavy_check_mark:|| [require-next-type](./docs/rules/require-next-type.md#readme) | Requires a type for `@next` tags |
|:heavy_check_mark:|:wrench:| [require-param](./docs/rules/require-param.md#readme) | Requires that all function parameters are documented with a `@param` tag. |
|:heavy_check_mark:|:wrench:| [require-param-description](./docs/rules/require-param-description.md#readme) | Requires that each `@param` tag has a `description` value. |
|:heavy_check_mark:|| [require-param-name](./docs/rules/require-param-name.md#readme) | Requires that all `@param` tags have names. |
|:heavy_check_mark: (Off in TS; On in TS flavor)|:wrench:| [require-param-type](./docs/rules/require-param-type.md#readme) | Requires that each `@param` tag has a type value (in curly brackets). |
|:heavy_check_mark:|:wrench:| [require-property](./docs/rules/require-property.md#readme) | Requires that all `@typedef` and `@namespace` tags have `@property` when their type is a plain `object`, `Object`, or `PlainObject`. |
|:heavy_check_mark:|| [require-property-description](./docs/rules/require-property-description.md#readme) | Requires that each `@property` tag has a `description` value. |
|:heavy_check_mark:|| [require-property-name](./docs/rules/require-property-name.md#readme) | Requires that all `@property` tags have names. |
|:heavy_check_mark: (Off in TS; On in TS flavor)|| [require-property-type](./docs/rules/require-property-type.md#readme) | Requires that each `@property` tag has a type value (in curly brackets). |
|:heavy_check_mark:|:wrench:| [require-returns](./docs/rules/require-returns.md#readme) | Requires that returns are documented with `@returns`. |
|:heavy_check_mark:|| [require-returns-check](./docs/rules/require-returns-check.md#readme) | Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present). |
|:heavy_check_mark:|| [require-returns-description](./docs/rules/require-returns-description.md#readme) | Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns). |
|:heavy_check_mark: (Off in TS; On in TS flavor)|| [require-returns-type](./docs/rules/require-returns-type.md#readme) | Requires that `@returns` tag has type value (in curly brackets). |
||| [require-tags](./docs/rules/require-tags.md#readme) | Requires tags be present, optionally for specific contexts |
||| [require-template](./docs/rules/require-template.md#readme) | Requires `@template` tags be present when type parameters are used. |
||| [require-template-description](./docs/rules/require-template-description.md#readme) | Requires a description for `@template` tags |
||| [require-throws](./docs/rules/require-throws.md#readme) | Requires that throw statements are documented with `@throws` tags. |
||| [require-throws-description](./docs/rules/require-throws-description.md#readme) | Requires a description for `@throws` tags |
|:heavy_check_mark:|| [require-throws-type](./docs/rules/require-throws-type.md#readme) | Requires a type for `@throws` tags |
|:heavy_check_mark:|| [require-yields](./docs/rules/require-yields.md#readme) | Requires yields are documented with `@yields` tags. |
|:heavy_check_mark:|| [require-yields-check](./docs/rules/require-yields-check.md#readme) | 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). |
||| [require-yields-description](./docs/rules/require-yields-description.md#readme) | Requires a description for `@yields` tags |
|:heavy_check_mark:|| [require-yields-type](./docs/rules/require-yields-type.md#readme) | Requires a type for `@yields` tags |
||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
|:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
||:wrench:| [type-formatting](./docs/rules/type-formatting.md#readme) | Formats JSDoc type values. |
|:heavy_check_mark:|| [valid-types](./docs/rules/valid-types.md#readme) | Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings). |