515 lines
30 KiB
Markdown
515 lines
30 KiB
Markdown
<a name="user-content-eslint-plugin-jsdoc"></a>
|
|
<a name="eslint-plugin-jsdoc"></a>
|
|
# eslint-plugin-jsdoc
|
|
|
|
[](https://www.npmjs.org/package/eslint-plugin-jsdoc)
|
|
[](https://travis-ci.org/gajus/eslint-plugin-jsdoc)
|
|
[](https://github.com/gajus/canonical)
|
|
[](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',
|
|
],
|
|
},
|
|
rejects: {
|
|
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/escape-inline-tags": 1, // Recommended for TS configs
|
|
"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/reject-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-rejects": 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/ts-method-signature-style": 1,
|
|
"jsdoc/ts-prefer-function-type": 1,
|
|
"jsdoc/ts-no-unnecessary-template-expression": 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:|:wrench:| [escape-inline-tags](./docs/rules/escape-inline-tags.md#readme) | Reports use of JSDoc tags in non-tag positions (in the default "typescript" mode). |
|
|
|: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). |
|
|
||| [require-rejects](./docs/rules/require-rejects.md#readme) | Requires that Promise rejections are documented with `@rejects` tags. |
|
|
|: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:| [ts-method-signature-style](./docs/rules/ts-method-signature-style.md#readme) | Prefers either function properties or method signatures |
|
|
|:heavy_check_mark:|| [ts-no-empty-object-type](./docs/rules/ts-no-empty-object-type.md#readme) | Warns against use of the empty object type |
|
|
||:wrench:| [ts-no-unnecessary-template-expression](./docs/rules/ts-no-unnecessary-template-expression.md#readme) | Catches unnecessary template expressions such as string expressions within a template literal. |
|
|
||:wrench:| [ts-prefer-function-type](./docs/rules/ts-prefer-function-type.md#readme) | Prefers function types over call signatures when there are no other properties. |
|
|
||: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). |
|