معرفی شرکت ها

eslint-plugin-jsdoc-41.1.1

Card image cap
تبلیغات ما

مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.

مشاهده بیشتر
Card image cap
تبلیغات ما

مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.

مشاهده بیشتر
Card image cap
تبلیغات ما

مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.

مشاهده بیشتر
Card image cap
تبلیغات ما

مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.

مشاهده بیشتر
Card image cap
تبلیغات ما

مشتریان به طور فزاینده ای آنلاین هستند. تبلیغات می تواند به آنها کمک کند تا کسب و کار شما را پیدا کنند.

مشاهده بیشتر
41.1.1
41.1.0
41.0.0
40.3.0
40.2.1
40.2.0
40.1.2
40.1.1
40.1.0
40.0.3
40.0.2
40.0.1
40.0.0
39.9.1
39.9.0
39.8.0
39.7.5
39.7.4
39.7.3
39.7.2
39.7.1
39.7.0
39.6.10
39.6.9
39.6.8
39.6.7
39.6.6
39.6.5
39.6.4
39.6.3
39.6.2
39.6.1
39.6.0
39.5.1
39.5.0
39.4.0
39.3.25
39.3.24
39.3.23
39.3.22
39.3.21
39.3.20
39.3.19
39.3.18
39.3.17
39.3.16
39.3.15
39.3.14
39.3.13
39.3.12
39.3.6
39.3.5
39.3.4
39.3.3
39.3.2
39.3.1
39.3.0
39.2.9
39.2.8
39.2.7
39.2.6
39.2.5
39.2.4
39.2.3
39.2.2
39.2.1
39.2.0
39.1.1
39.1.0
39.0.1
39.0.0
38.1.6
38.1.5
38.1.4
38.1.3
38.1.2
38.1.1
38.1.0
38.0.8
38.0.7
38.0.6
38.0.5
38.0.4
38.0.3
38.0.2
38.0.1
38.0.0
37.9.7
37.9.6
37.9.5
37.9.4
37.9.3
37.9.2
37.9.1
37.9.0
37.8.2
37.8.1
37.8.0
37.7.1
37.7.0
37.6.3
37.6.2
37.6.1
37.6.0
37.5.2
37.5.1
37.5.0
37.4.2
37.4.1
37.4.0
37.3.0
37.2.8
37.2.7
37.2.6
37.2.5
37.2.4
37.2.3
37.2.2
37.2.1
37.2.0
37.1.0
37.0.3
37.0.2
37.0.1
37.0.0
36.1.1
36.1.0
36.0.8
36.0.7
36.0.6
36.0.5
36.0.4
36.0.3
36.0.2
36.0.1
36.0.0
35.5.1
35.5.0
35.4.7
35.4.6
35.4.5
35.4.4
35.4.3
35.4.2
35.4.1
35.4.0
35.3.2
35.3.1
35.3.0
35.2.0
35.1.3
35.1.2
35.1.1
35.1.0
35.0.0
34.8.2
34.8.1
34.8.0
34.7.0
34.6.3
34.6.2
34.6.1
34.6.0
34.5.0
34.4.0
34.3.0
34.2.2
34.2.1
34.2.0
34.1.0
34.0.2
34.0.1
34.0.0
33.3.0
33.2.0
33.1.1
33.1.0
33.0.0
32.3.4
32.3.3
32.3.2
32.3.1
32.3.0
32.2.0
32.1.1
32.1.0
32.0.3
32.0.2
32.0.1
32.0.0
31.6.1
31.6.0
31.5.0
31.4.0
31.3.3
31.3.2
31.3.1
31.3.0
31.2.3
31.2.2
31.2.1
31.2.0
31.1.0
31.0.8
31.0.7
31.0.6
31.0.5
31.0.4
31.0.3
31.0.2
31.0.1
31.0.0
30.7.13
30.7.12
30.7.11
30.7.10
30.7.9
30.7.8
30.7.7
30.7.6
30.7.5
30.7.4
30.7.3
30.7.2
30.7.1
30.7.0
30.6.5
30.6.4
30.6.3
30.6.2
30.6.1
30.6.0
30.5.3
30.5.2
30.5.1
30.5.0
30.4.2
30.4.1
30.4.0
30.3.3
30.3.2
30.3.1
30.3.0
30.2.4
30.2.3
30.2.2
30.2.1
30.2.0
30.1.0
30.0.3
30.0.2
30.0.1
30.0.0
29.2.0
29.1.4
29.1.3
29.1.2
29.1.1
29.1.0
29.0.0
28.7.0
28.6.1
28.6.0
28.5.1
28.5.0
28.4.0
28.3.0
28.2.0
28.1.0
28.0.0
27.1.2
27.1.1
27.1.0
27.0.7
27.0.6
27.0.5
27.0.4
27.0.3
27.0.2
27.0.1
27.0.0
26.0.2
26.0.1
26.0.0
25.4.3
25.4.2
25.4.1
25.4.0
25.3.1
25.3.0
25.2.1
25.2.0
25.1.0
25.0.1
25.0.0
24.0.6
24.0.5
24.0.4
24.0.3
24.0.2
24.0.1
24.0.0
23.1.0
23.0.1
23.0.0
22.2.0
22.1.0
22.0.1
22.0.0
21.0.0
20.4.0
20.3.1
20.3.0
20.2.0
20.1.0
20.0.5
20.0.4
20.0.3
20.0.2
20.0.1
20.0.0
19.2.0
19.1.0
19.0.1
19.0.0
18.11.0
18.10.0
18.9.0
18.8.0
18.7.0
18.6.2
18.6.1
18.6.0
18.5.0
18.4.4
18.4.3
18.4.2
18.4.1
18.4.0
18.3.0
18.2.2
18.2.1
18.2.0
18.1.6
18.1.5
18.1.4
18.1.3
18.1.2
18.1.1
18.1.0
18.0.1
18.0.0
17.1.2
17.1.1
17.1.0
17.0.1
17.0.0
16.1.1
16.1.0
16.0.0
15.12.2
15.12.1
15.12.0
15.11.1
15.11.0
15.10.1
15.10.0
15.9.10
15.9.9
15.9.8
15.9.7
15.9.6
15.9.5
15.9.4
15.9.3
15.9.2
15.9.1
15.9.0
15.8.4
15.8.3
15.8.2
15.8.1
15.8.0
15.7.2
15.7.1
15.7.0
15.6.2
15.6.1
15.6.0
15.5.6
15.5.5
15.5.4
15.5.3
15.5.2
15.5.1
15.5.0
15.4.2
15.4.1
15.4.0
15.3.9
15.3.8
15.3.7
15.3.6
15.3.5
15.3.4
15.3.3
15.3.2
15.3.1
15.3.0
15.2.0
15.1.0
15.0.1
15.0.0
14.1.0
14.0.0
13.0.0
12.0.0
11.2.1
11.2.0
11.1.0
11.0.0
10.3.0
10.2.0
10.1.1
10.1.0
10.0.3
10.0.2
10.0.1
10.0.0
9.1.0
9.0.1
9.0.0
8.7.0
8.6.2
8.6.1
8.6.0
8.5.1
8.5.0
8.4.6
8.4.5
8.4.4
8.4.3
8.4.2
8.4.1
8.4.0
8.3.2
8.3.1
8.3.0
8.2.0
8.1.0
8.0.2
8.0.1
8.0.0
7.2.3
7.2.2
7.2.1
7.2.0
7.1.0
7.0.2
7.0.1
7.0.0
6.0.3
6.0.2
6.0.1
6.0.0
5.0.2
5.0.1
5.0.0
4.8.4
4.8.3
4.8.2
4.8.1
4.8.0
4.7.0
4.6.0
4.5.0
4.4.3
4.4.2
4.4.1
4.4.0
4.3.0
4.2.0
4.1.1
4.1.0
4.0.1
4.0.0
3.15.1
3.15.0
3.14.1
3.14.0
3.13.0
3.12.1
3.12.0
3.11.0
3.10.0
3.9.1
3.9.0
3.8.0
3.7.2
3.7.1
3.7.0
3.6.3
3.6.2
3.6.1
3.6.0
3.5.0
3.4.1
3.4.0
3.3.1
3.3.0
3.2.0
3.1.3
3.1.2
3.1.1
3.1.0
3.0.2
3.0.1
3.0.0
2.4.0
2.3.1
2.3.0
2.2.4
2.2.3
2.2.2
2.2.1
2.2.0
2.1.4
2.1.3
2.1.2
2.1.1
2.1.0
2.0.4
2.0.3
2.0.2
2.0.1
1.1.3
1.1.2
1.1.0
1.0.1
0.0.2
0.0.1
0.0.0

توضیحات

JSDoc linting rules for ESLint.
ویژگی مقدار
سیستم عامل -
نام فایل eslint-plugin-jsdoc-41.1.1
نام eslint-plugin-jsdoc
نسخه کتابخانه 41.1.1
نگهدارنده ['gajus']
ایمیل نگهدارنده ['gajus@gajus.com']
نویسنده Gajus Kuizinas
ایمیل نویسنده gajus@gajus.com
آدرس صفحه اصلی git+https://github.com/gajus/eslint-plugin-jsdoc.git
آدرس اینترنتی https://github.com/gajus/eslint-plugin-jsdoc#readme
مجوز BSD-3-Clause
<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) * [Options](#user-content-eslint-plugin-jsdoc-options) * [Settings](#user-content-eslint-plugin-jsdoc-settings) * [Allow tags (`@private` or `@internal`) to disable rules for that comment block](#user-content-eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block) * [`maxLines` and `minLines`](#user-content-eslint-plugin-jsdoc-settings-maxlines-and-minlines) * [Mode](#user-content-eslint-plugin-jsdoc-settings-mode) * [Alias Preference](#user-content-eslint-plugin-jsdoc-settings-alias-preference) * [`@override`/`@augments`/`@extends`/`@implements`/`@ignore` Without Accompanying `@param`/`@description`/`@example`/`@returns`/`@throws`/`@yields`](#user-content-eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields) * [Settings to Configure `check-types` and `no-undefined-types`](#user-content-eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types) * [`structuredTags`](#user-content-eslint-plugin-jsdoc-settings-structuredtags) * [`contexts`](#user-content-eslint-plugin-jsdoc-settings-contexts) * [Advanced](#user-content-eslint-plugin-jsdoc-advanced) * [AST and Selectors](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors) * [Rules](#user-content-eslint-plugin-jsdoc-rules) * [`check-access`](#user-content-eslint-plugin-jsdoc-rules-check-access) * [`check-alignment`](#user-content-eslint-plugin-jsdoc-rules-check-alignment) * [`check-examples`](#user-content-eslint-plugin-jsdoc-rules-check-examples) * [`check-indentation`](#user-content-eslint-plugin-jsdoc-rules-check-indentation) * [`check-line-alignment`](#user-content-eslint-plugin-jsdoc-rules-check-line-alignment) * [`check-param-names`](#user-content-eslint-plugin-jsdoc-rules-check-param-names) * [`check-property-names`](#user-content-eslint-plugin-jsdoc-rules-check-property-names) * [`check-syntax`](#user-content-eslint-plugin-jsdoc-rules-check-syntax) * [`check-tag-names`](#user-content-eslint-plugin-jsdoc-rules-check-tag-names) * [`check-types`](#user-content-eslint-plugin-jsdoc-rules-check-types) * [`check-values`](#user-content-eslint-plugin-jsdoc-rules-check-values) * [`empty-tags`](#user-content-eslint-plugin-jsdoc-rules-empty-tags) * [`implements-on-classes`](#user-content-eslint-plugin-jsdoc-rules-implements-on-classes) * [`informative-docs`](#user-content-eslint-plugin-jsdoc-rules-informative-docs) * [`match-description`](#user-content-eslint-plugin-jsdoc-rules-match-description) * [`match-name`](#user-content-eslint-plugin-jsdoc-rules-match-name) * [`multiline-blocks`](#user-content-eslint-plugin-jsdoc-rules-multiline-blocks) * [`newline-after-description`](#user-content-eslint-plugin-jsdoc-rules-newline-after-description) * [`no-bad-blocks`](#user-content-eslint-plugin-jsdoc-rules-no-bad-blocks) * [`no-blank-block-descriptions`](#user-content-eslint-plugin-jsdoc-rules-no-blank-block-descriptions) * [`no-defaults`](#user-content-eslint-plugin-jsdoc-rules-no-defaults) * [`no-missing-syntax`](#user-content-eslint-plugin-jsdoc-rules-no-missing-syntax) * [`no-multi-asterisks`](#user-content-eslint-plugin-jsdoc-rules-no-multi-asterisks) * [`no-restricted-syntax`](#user-content-eslint-plugin-jsdoc-rules-no-restricted-syntax) * [`no-types`](#user-content-eslint-plugin-jsdoc-rules-no-types) * [`no-undefined-types`](#user-content-eslint-plugin-jsdoc-rules-no-undefined-types) * [`require-asterisk-prefix`](#user-content-eslint-plugin-jsdoc-rules-require-asterisk-prefix) * [`require-description-complete-sentence`](#user-content-eslint-plugin-jsdoc-rules-require-description-complete-sentence) * [`require-description`](#user-content-eslint-plugin-jsdoc-rules-require-description) * [`require-example`](#user-content-eslint-plugin-jsdoc-rules-require-example) * [`require-file-overview`](#user-content-eslint-plugin-jsdoc-rules-require-file-overview) * [`require-hyphen-before-param-description`](#user-content-eslint-plugin-jsdoc-rules-require-hyphen-before-param-description) * [`require-jsdoc`](#user-content-eslint-plugin-jsdoc-rules-require-jsdoc) * [`require-param-description`](#user-content-eslint-plugin-jsdoc-rules-require-param-description) * [`require-param-name`](#user-content-eslint-plugin-jsdoc-rules-require-param-name) * [`require-param-type`](#user-content-eslint-plugin-jsdoc-rules-require-param-type) * [`require-param`](#user-content-eslint-plugin-jsdoc-rules-require-param) * [`require-property`](#user-content-eslint-plugin-jsdoc-rules-require-property) * [`require-property-description`](#user-content-eslint-plugin-jsdoc-rules-require-property-description) * [`require-property-name`](#user-content-eslint-plugin-jsdoc-rules-require-property-name) * [`require-property-type`](#user-content-eslint-plugin-jsdoc-rules-require-property-type) * [`require-returns-check`](#user-content-eslint-plugin-jsdoc-rules-require-returns-check) * [`require-returns-description`](#user-content-eslint-plugin-jsdoc-rules-require-returns-description) * [`require-returns-type`](#user-content-eslint-plugin-jsdoc-rules-require-returns-type) * [`require-returns`](#user-content-eslint-plugin-jsdoc-rules-require-returns) * [`require-throws`](#user-content-eslint-plugin-jsdoc-rules-require-throws) * [`require-yields`](#user-content-eslint-plugin-jsdoc-rules-require-yields) * [`require-yields-check`](#user-content-eslint-plugin-jsdoc-rules-require-yields-check) * [`sort-tags`](#user-content-eslint-plugin-jsdoc-rules-sort-tags) * [`tag-lines`](#user-content-eslint-plugin-jsdoc-rules-tag-lines) * [`text-escaping`](#user-content-eslint-plugin-jsdoc-rules-text-escaping) * [`valid-types`](#user-content-eslint-plugin-jsdoc-rules-valid-types) <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 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, "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-types": 1, // Recommended "jsdoc/check-values": 1, // Recommended "jsdoc/empty-tags": 1, // Recommended "jsdoc/implements-on-classes": 1, // Recommended "jsdoc/match-description": 1, "jsdoc/multiline-blocks": 1, // Recommended "jsdoc/newline-after-description": 1, // Recommended "jsdoc/no-bad-blocks": 1, "jsdoc/no-defaults": 1, "jsdoc/no-missing-syntax": 1, "jsdoc/no-multi-asterisks": 1, // Recommended "jsdoc/no-restricted-syntax": 1, "jsdoc/no-types": 1, "jsdoc/no-undefined-types": 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-param": 1, // Recommended "jsdoc/require-param-description": 1, // Recommended "jsdoc/require-param-name": 1, // Recommended "jsdoc/require-param-type": 1, // Recommended "jsdoc/require-property": 1, // Recommended "jsdoc/require-property-description": 1, // Recommended "jsdoc/require-property-name": 1, // Recommended "jsdoc/require-property-type": 1, // Recommended "jsdoc/require-returns": 1, // Recommended "jsdoc/require-returns-check": 1, // Recommended "jsdoc/require-returns-description": 1, // Recommended "jsdoc/require-returns-type": 1, // Recommended "jsdoc/require-throws": 1, "jsdoc/require-yields": 1, // Recommended "jsdoc/require-yields-check": 1, // Recommended "jsdoc/sort-tags": 1, "jsdoc/tag-lines": 1, // Recommended "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 configure the following: ```javascript { "rules": { "jsdoc/no-types": 1, "jsdoc/require-param-type": 0, "jsdoc/require-property-type": 0, "jsdoc/require-returns-type": 0, } } ``` ...or just use: ```json { "extends": ["plugin:jsdoc/recommended-typescript"] } ``` ...or to report with failing errors instead of mere warnings: ```json { "extends": ["plugin:jsdoc/recommended-typescript-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 <a name="user-content-eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block"></a> <a name="eslint-plugin-jsdoc-settings-allow-tags-private-or-internal-to-disable-rules-for-that-comment-block"></a> ### Allow tags (<code>@private</code> or <code>@internal</code>) to disable rules for that comment block - `settings.jsdoc.ignorePrivate` - Disables all rules for the comment block on which a `@private` tag (or `@access private`) occurs. Defaults to `false`. Note: This has no effect with the rule `check-access` (whose purpose is to check access modifiers) or `empty-tags` (which checks `@private` itself). - `settings.jsdoc.ignoreInternal` - Disables all rules for the comment block on which a `@internal` tag occurs. Defaults to `false`. Note: This has no effect with the rule `empty-tags` (which checks `@internal` itself). <a name="user-content-eslint-plugin-jsdoc-settings-maxlines-and-minlines"></a> <a name="eslint-plugin-jsdoc-settings-maxlines-and-minlines"></a> ### <code>maxLines</code> and <code>minLines</code> One can use `minLines` and `maxLines` to indicate how many line breaks (if any) will be checked to find a jsdoc comment block before the given code block. These settings default to `0` and `1` respectively. In conjunction with the `require-jsdoc` rule, these settings can be enforced so as to report problems if a jsdoc block is not found within the specified boundaries. The settings are also used in the fixer to determine how many line breaks to add when a block is missing. <a name="user-content-eslint-plugin-jsdoc-settings-mode"></a> <a name="eslint-plugin-jsdoc-settings-mode"></a> ### Mode - `settings.jsdoc.mode` - Set to `typescript`, `closure`, or `jsdoc` (the default unless the `@typescript-eslint` parser is in use in which case `typescript` will be the default). Note that if you do not wish to use separate `.eslintrc.*` files for a project containing both JavaScript and TypeScript, you can also use [`overrides`](https://eslint.org/docs/user-guide/configuring). You may also set to `"permissive"` to try to be as accommodating to any of the styles, but this is not recommended. Currently is used for the following: - `check-tag-names`: Determine valid tags and aliases - `no-undefined-types`: Only check `@template` for types in "closure" and "typescript" modes - `check-syntax`: determines aspects that may be enforced - `valid-types`: in non-Closure mode, `@extends`, `@package` and access tags (e.g., `@private`) with a bracketed type are reported as are missing names with `@typedef` - For type/namepath-checking rules, determine which tags will be checked for types/namepaths (Closure allows types on some tags which the others do not, so these tags will additionally be checked in "closure" mode) - For type-checking rules, impacts parsing of types (through [jsdoc-type-pratt-parser](https://github.com/simonseyock/jsdoc-type-pratt-parser) dependency) - Check preferred tag names - Disallows namepath on `@interface` for "closure" mode in `valid-types` (and avoids checking in other rules) <a name="user-content-eslint-plugin-jsdoc-settings-alias-preference"></a> <a name="eslint-plugin-jsdoc-settings-alias-preference"></a> ### 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. ```json { "rules": {}, "settings": { "jsdoc": { "tagNamePreference": { "param": "arg", "returns": "return" } } } } ``` Note: ESLint does not allow settings to have keys which conflict with `Object.prototype` e.g. `'constructor'`. To work around this, you can use the key `'tag constructor'`. One may also use an object with a `message` and `replacement`. The following will report the message `@extends is to be used over @augments as it is more evocative of classes than @augments` upon encountering `@augments`. ```json { "rules": {}, "settings": { "jsdoc": { "tagNamePreference": { "augments": { "message": "@extends is to be used over @augments as it is more evocative of classes than @augments", "replacement": "extends" } } } } } ``` If one wishes to reject a normally valid tag, e.g., `@todo`, one may set the tag to `false`: ```json { "rules": {}, "settings": { "jsdoc": { "tagNamePreference": { "todo": false } } } } ``` A project wishing to ensure no blocks are left excluded from entering the documentation, might wish to prevent the `@ignore` tag in the above manner. Or one may set the targeted tag to an object with a custom `message`, but without a `replacement` property: ```json { "rules": {}, "settings": { "jsdoc": { "tagNamePreference": { "todo": { "message": "We expect immediate perfection, so don't leave to-dos in your code." } } } } } ``` Note that the preferred tags indicated in the `settings.jsdoc.tagNamePreference` map will be assumed to be defined by `check-tag-names`. See `check-tag-names` for how that fact can be used to set an alias to itself to allow both the alias and the default (since aliases are otherwise not permitted unless used in `tagNamePreference`). <a name="user-content-eslint-plugin-jsdoc-settings-alias-preference-default-preferred-aliases"></a> <a name="eslint-plugin-jsdoc-settings-alias-preference-default-preferred-aliases"></a> #### Default Preferred Aliases The defaults in `eslint-plugin-jsdoc` (for tags which offer aliases) are as follows: - `@abstract` (over `@virtual`) - `@augments` (over `@extends`) - `@class` (over `@constructor`) - `@constant` (over `@const`) - `@default` (over `@defaultvalue`) - `@description` (over `@desc`) - `@external` (over `@host`) - `@file` (over `@fileoverview`, `@overview`) - `@fires` (over `@emits`) - `@function` (over `@func`, `@method`) - `@member` (over `@var`) - `@param` (over `@arg`, `@argument`) - `@property` (over `@prop`) - `@returns` (over `@return`) - `@throws` (over `@exception`) - `@yields` (over `@yield`) This setting is utilized by the the rule for tag name checking (`check-tag-names`) as well as in the `@param` and `@require` rules: - `check-param-names` - `check-tag-names` - `require-hyphen-before-param-description` - `require-description` - `require-param` - `require-param-description` - `require-param-name` - `require-param-type` - `require-returns` - `require-returns-check` - `require-returns-description` - `require-returns-type` <a name="user-content-eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields"></a> <a name="eslint-plugin-jsdoc-settings-override-augments-extends-implements-ignore-without-accompanying-param-description-example-returns-throws-yields"></a> ### <code>@override</code>/<code>@augments</code>/<code>@extends</code>/<code>@implements</code>/<code>@ignore</code> Without Accompanying <code>@param</code>/<code>@description</code>/<code>@example</code>/<code>@returns</code>/<code>@throws</code>/<code>@yields</code> The following settings allows the element(s) they reference to be omitted on the JSDoc comment block of the function or that of its parent class for any of the "require" rules (i.e., `require-param`, `require-description`, `require-example`, `require-returns`, `require-throws`, `require-yields`). * `settings.jsdoc.ignoreReplacesDocs` (`@ignore`) - Defaults to `true` * `settings.jsdoc.overrideReplacesDocs` (`@override`) - Defaults to `true` * `settings.jsdoc.augmentsExtendsReplacesDocs` (`@augments` or its alias `@extends`) - Defaults to `false`. * `settings.jsdoc.implementsReplacesDocs` (`@implements`) - Defaults to `false` The format of the configuration is as follows: ```json { "rules": {}, "settings": { "jsdoc": { "ignoreReplacesDocs": true, "overrideReplacesDocs": true, "augmentsExtendsReplacesDocs": true, "implementsReplacesDocs": true } } } ``` <a name="user-content-eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types"></a> <a name="eslint-plugin-jsdoc-settings-settings-to-configure-check-types-and-no-undefined-types"></a> ### Settings to Configure <code>check-types</code> and <code>no-undefined-types</code> - `settings.jsdoc.preferredTypes` An option map to indicate preferred or forbidden types (if default types are indicated here, these will have precedence over the default recommendations for `check-types`). The keys of this map are the types to be replaced (or forbidden). These keys may include: 1. The "ANY" type, `*` 1. The pseudo-type `[]` which we use to denote the parent (array) types used in the syntax `string[]`, `number[]`, etc. 1. The pseudo-type `.<>` (or `.`) to represent the format `Array.<value>` or `Object.<key, value>` 1. The pseudo-type `<>` to represent the format `Array<value>` or `Object<key, value>` 1. A plain string type, e.g., `MyType` 1. A plain string type followed by one of the above pseudo-types (except for `[]` which is always assumed to be an `Array`), e.g., `Array.`, or `SpecialObject<>`. If a bare pseudo-type is used, it will match all parent types of that form. If a pseudo-type prefixed with a type name is used, it will only match parent types of that form and type name. The values can be: - `false` to forbid the type - a string to indicate the type that should be preferred in its place (and which `fix` mode can replace); this can be one of the formats of the keys described above. - Note that the format will not be changed unless you use a pseudo-type in the replacement. (For example, `'Array.<>': 'MyArray'` will change `Array.<string>` to `MyArray.<string>`, preserving the dot. To get rid of the dot, you must use the pseudo-type with `<>`, i.e., `'Array.<>': 'MyArray<>'`, which will change `Array.<string>` to `MyArray<string>`). - If you use a _bare_ pseudo-type in the replacement (e.g., `'MyArray.<>': '<>'`), the type will be converted to the format of the pseudo-type without changing the type name. For example, `MyArray.<string>` will become `MyArray<string>` but `Array.<string>` will not be modified. - an object with: - the key `message` to provide a specific error message when encountering the discouraged type. - The message string will have the substrings with special meaning, `{{tagName}}` and `{{tagValue}}`, replaced with their corresponding value. - an optional key `replacement` with either of the following values: - a string type to be preferred in its place (and which `fix` mode can replace) - `false` (for forbidding the type) - an optional key `skipRootChecking` (for `check-types`) to allow for this type in the context of a root (i.e., a parent object of some child type) Note that the preferred types indicated as targets in `settings.jsdoc.preferredTypes` map will be assumed to be defined by `no-undefined-types`. See the option of `check-types`, `unifyParentAndChildTypeChecks`, for how the keys of `preferredTypes` may have `<>` or `.<>` (or just `.`) appended and its bearing on whether types are checked as parents/children only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`). Note that if a value is present both as a key and as a value, neither the key nor the value will be reported. Thus in `check-types`, this fact can be used to allow both `object` and `Object` if one has a `preferredTypes` key `object: 'Object'` and `Object: 'object'`. <a name="user-content-eslint-plugin-jsdoc-settings-structuredtags"></a> <a name="eslint-plugin-jsdoc-settings-structuredtags"></a> ### <code>structuredTags</code> An object indicating tags whose types and names/namepaths (whether defining or referencing namepaths) will be checked, subject to configuration. If the tags have predefined behavior or `allowEmptyNamepaths` behavior, this option will override that behavior for any specified tags, though this option can also be used for tags without predefined behavior. Its keys are tag names and its values are objects with the following optional properties: - `name` - String set to one of the following: - `"text"` - When a name is present, plain text will be allowed in the name position (non-whitespace immediately after the tag and whitespace), e.g., in `@throws This is an error`, "This" would normally be the name, but "text" allows non-name text here also. This is the default. - `"namepath-defining"` - As with `namepath-referencing`, but also indicates the tag adds a namepath to definitions, e.g., to prevent `no-undefined-types` from reporting references to that namepath. - `"namepath-referencing"` - This will cause any name position to be checked to ensure it is a valid namepath. You might use this to ensure that tags which normally allow free text, e.g., `@see` will instead require a namepath. - `false` - This will disallow any text in the name position. - `type`: - `true` - Allows valid types within brackets. This is the default. - `false` - Explicitly disallows any brackets or bracketed type. You might use this with `@throws` to suggest that only free form text is being input or with `@augments` (for jsdoc mode) to disallow Closure-style bracketed usage along with a required namepath. - (An array of strings) - A list of permissible types. - `required` - Array of one of the following (defaults to an empty array, meaning none are required): - One or both of the following strings (if both are included, then both are required): - `"name"` - Indicates that a name position is required (not just that if present, it is a valid namepath). You might use this with `see` to insist that a value (or namepath, depending on the `name` value) is always present. - `"type"` - Indicates that the type position (within curly brackets) is required (not just that if present, it is a valid type). You might use this with `@throws` or `@typedef` which might otherwise normally have their types optional. See the type groups 3-5 above. - `"typeOrName"` - Must have either type (e.g., `@throws {aType}`) or name (`@throws Some text`); does not require that both exist but disallows just an empty tag. <a name="user-content-eslint-plugin-jsdoc-settings-contexts"></a> <a name="eslint-plugin-jsdoc-settings-contexts"></a> ### <code>contexts</code> `settings.jsdoc.contexts` can be used as the default for any rules with a `contexts` property option. See the "AST and Selectors" section for more on this format. <a name="user-content-eslint-plugin-jsdoc-advanced"></a> <a name="eslint-plugin-jsdoc-advanced"></a> ## Advanced <a name="user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors"></a> <a name="eslint-plugin-jsdoc-advanced-ast-and-selectors"></a> ### AST and Selectors For various rules, one can add to the environments to which the rule applies by using the `contexts` option. This option works with [ESLint's selectors](https://eslint.org/docs/developer-guide/selectors) which are [esquery](https://github.com/estools/esquery/#readme) expressions one may use to target a specific node type or types, including subsets of the type(s) such as nodes with certain children or attributes. These expressions are used within ESLint plugins to find those parts of your files' code which are of interest to check. However, in `eslint-plugin-jsdoc`, we also allow you to use these selectors to define additional contexts where you wish our own rules to be applied. <a name="user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors-contexts-format"></a> <a name="eslint-plugin-jsdoc-advanced-ast-and-selectors-contexts-format"></a> #### <code>contexts</code> format While at their simplest, these can be an array of string selectors, one can also supply an object with `context` (in place of the string) and one of two properties: 1. For `require-jsdoc`, there are also `inlineCommentBlock` and `minLineCount` properties. See that rule for details. 1. For `no-missing-syntax` and `no-restricted-syntax`, there is also a `message` property which allows customization of the message to be shown when the rule is triggered. 1. For `no-missing-syntax`, there is also a `minimum` property. See that rule. 1. For other rules, there is a `comment` property which adds to the `context` in requiring that the `comment` AST condition is also met, e.g., to require that certain tags are present and/or or types and type operators are in use. Note that this AST (either for `Jsdoc*` or `JsdocType*` AST) has not been standardized and should be considered experimental. Note that this property might also become obsolete if parsers begin to include JSDoc-structured AST. A [parser](https://github.com/brettz9/jsdoc-eslint-parser/) is available which aims to support comment AST as a first class citizen where comment/comment types can be used anywhere within a normal AST selector but this should only be considered experimental. When using such a parser, you need not use `comment` and can just use a plain string context. The determination of the node on which the comment is attached is based more on actual location than semantics (e.g., it will be attached to a `VariableDeclaration` if above that rather than to the `FunctionExpression` it is fundamentally describing). See [@es-joy/jsdoccomment](https://github.com/es-joy/jsdoccomment) for the precise structure of the comment (and comment type) nodes. <a name="user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors-discovering-available-ast-definitions"></a> <a name="eslint-plugin-jsdoc-advanced-ast-and-selectors-discovering-available-ast-definitions"></a> #### Discovering available AST definitions To know all of the AST definitions one may target, it will depend on the [parser](https://eslint.org/docs/user-guide/configuring#specifying-parser) you are using with ESLint (e.g., `espree` is the default parser for ESLint, and this follows [EStree AST](https://github.com/estree/estree) but to support the the latest experimental features of JavaScript, one may use `@babel/eslint-parser` or to be able to have one's rules (including JSDoc rules) apply to TypeScript, one may use `@typescript-eslint/parser`, etc. So you can look up a particular parser to see its rules, e.g., browse through the [ESTree docs](https://github.com/estree/estree) as used by Espree or see ESLint's [overview of the structure of AST](https://eslint.org/docs/developer-guide/working-with-custom-parsers#the-ast-specification). However, it can sometimes be even more helpful to get an idea of AST by just providing some of your JavaScript to the wonderful [AST Explorer](https://astexplorer.net/) tool and see what AST is built out of your code. You can set the tool to the specific parser which you are using. <a name="user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors-uses-tips-for-ast"></a> <a name="eslint-plugin-jsdoc-advanced-ast-and-selectors-uses-tips-for-ast"></a> #### Uses/Tips for AST And if you wish to introspect on the AST of code within your projects, you can use [eslint-plugin-query](https://github.com/brettz9/eslint-plugin-query). Though it also works as a plugin, you can use it with its own CLI, e.g., to search your files for matching esquery selectors, optionally showing it as AST JSON. Tip: If you want to more deeply understand not just the resulting AST tree structures for any given code but also the syntax for esquery selectors so that you can, for example, find only those nodes with a child of a certain type, you can set the "Transform" feature to ESLint and test out esquery selectors in place of the selector expression (e.g., replace `'VariableDeclaration > VariableDeclarator > Identifier[name="someVar"]'` as we have [here](https://astexplorer.net/#/gist/71a93130c19599d6f197bddb29c13a59/latest)) to the selector you wish so as to get messages reported in the bottom right pane which match your [esquery](https://github.com/estools/esquery/#readme) selector). <a name="user-content-eslint-plugin-jsdoc-rules"></a> <a name="eslint-plugin-jsdoc-rules"></a> ## Rules <a name="user-content-eslint-plugin-jsdoc-rules-check-access"></a> <a name="eslint-plugin-jsdoc-rules-check-access"></a> ### <code>check-access</code> Checks that `@access` tags use one of the following values: - "package", "private", "protected", "public" Also reports: - Mixing of `@access` with `@public`, `@private`, `@protected`, or `@package` on the same doc block. - Use of multiple instances of `@access` (or the `@public`, etc. style tags) on the same doc block. ||| |---|---| |Context|everywhere| |Tags|`@access`| |Recommended|false| |Settings|| |Options|| The following patterns are considered problems: ````js /** * @access foo */ function quux (foo) { } // Message: Missing valid JSDoc @access level. /** * @access foo */ function quux (foo) { } // Settings: {"jsdoc":{"ignorePrivate":true}} // Message: Missing valid JSDoc @access level. /** * @accessLevel foo */ function quux (foo) { } // Settings: {"jsdoc":{"tagNamePreference":{"access":"accessLevel"}}} // Message: Missing valid JSDoc @accessLevel level. /** * @access */ function quux (foo) { } // Settings: {"jsdoc":{"tagNamePreference":{"access":false}}} // Message: Unexpected tag `@access` class MyClass { /** * @access */ myClassField = 1 } // Message: Missing valid JSDoc @access level. /** * @access public * @public */ function quux (foo) { } // Message: The @access tag may not be used with specific access-control tags (@package, @private, @protected, or @public). /** * @access public * @access private */ function quux (foo) { } // Message: At most one access-control tag may be present on a jsdoc block. /** * @access public * @access private */ function quux (foo) { } // Settings: {"jsdoc":{"ignorePrivate":true}} // Message: At most one access-control tag may be present on a jsdoc block. /** * @public * @private */ function quux (foo) { } // Message: At most one access-control tag may be present on a jsdoc block. /** * @public * @private */ function quux (foo) { } // Settings: {"jsdoc":{"ignorePrivate":true}} // Message: At most one access-control tag may be present on a jsdoc block. /** * @public * @public */ function quux (foo) { } // Message: At most one access-control tag may be present on a jsdoc block. ```` The following patterns are not considered problems: ````js /** * */ function quux (foo) { } /** * @access public */ function quux (foo) { } /** * @accessLevel package */ function quux (foo) { } // Settings: {"jsdoc":{"tagNamePreference":{"access":"accessLevel"}}} class MyClass { /** * @access private */ myClassField = 1 } /** * @public */ function quux (foo) { } /** * @private */ function quux (foo) { } // Settings: {"jsdoc":{"ignorePrivate":true}} ```` <a name="user-content-eslint-plugin-jsdoc-rules-check-alignment"></a> <a name="eslint-plugin-jsdoc-rules-check-alignment"></a> ### <code>check-alignment</code> Reports invalid alignment of JSDoc block asterisks. ||| |---|---| |Context|everywhere| |Tags|N/A| |Recommended|true| The following patterns are considered problems: ````js /** * @param {Number} foo */ function quux (foo) { // with spaces } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { // with tabs } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { // with spaces } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { // with spaces } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { } // Message: Expected JSDoc block to be aligned. /** * @param {Number} foo */ function quux (foo) { } // Message: Expected JSDoc block to be aligned. /** * A jsdoc not attached to any node. */ // Message: Expected JSDoc block to be aligned. class Foo { /** * Some method * @param a */ quux(a) {} } // Message: Expected JSDoc block to be aligned. ```` The following patterns are not considered problems: ````js /** * Desc * * @param {Number} foo */ function quux (foo) { } /** * Desc * * @param {{ foo: Bar, bar: Baz * }} foo * */ function quux (foo) { } /* <- JSDoc must start with 2 stars. * So this is unchecked. */ function quux (foo) {} /** * @param {Number} foo * @private */ function quux (foo) { // with spaces } // Settings: {"jsdoc":{"ignorePrivate":true}} /** * @param {Number} foo * @access private */ function quux (foo) { // with spaces } // Settings: {"jsdoc":{"ignorePrivate":true}} ```` <a name="user-content-eslint-plugin-jsdoc-rules-check-examples"></a> <a name="eslint-plugin-jsdoc-rules-check-examples"></a> ### <code>check-examples</code> > **NOTE**: This rule currently does not work in ESLint 8 (we are waiting for > [issue 14745](https://github.com/eslint/eslint/issues/14745)). Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules. Also has options to lint the default values of optional `@param`/`@arg`/`@argument` and `@property`/`@prop` tags or the values of `@default`/`@defaultvalue` tags. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-1"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-1"></a> #### Options The options below all default to no-op/`false` except as noted. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-1-captionrequired"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-1-captionrequired"></a> ##### <code>captionRequired</code> JSDoc specs use of an optional `<caption>` element at the beginning of `@example`. The option `captionRequired` insists on a `<caption>` being present at the beginning of any `@example`. Used only for `@example`. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-1-examplecoderegex-and-rejectexamplecoderegex"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-1-examplecoderegex-and-rejectexamplecoderegex"></a> ##### <code>exampleCodeRegex</code> and <code>rejectExampleCodeRegex</code> JSDoc does not specify a formal means for delimiting code blocks within `@example` (it uses generic syntax highlighting techniques for its own syntax highlighting). The following options determine whether a given `@example` tag will have the `check-examples` checks applied to it: * `exampleCodeRegex` - Regex which whitelists lintable examples. If a parenthetical group is used, the first one will be used, so you may wish to use `(?:...)` groups where you do not wish the first such group treated as one to include. If no parenthetical group exists or matches, the whole matching expression will be used. An example might be ````"^```(?:js|javascript)([\\s\\S]*)```\s*$"```` to only match explicitly fenced JavaScript blocks. Defaults to only using the `u` flag, so to add your own flags, encapsulate your expression as a string, but like a literal, e.g., ````/```js.*```/gi````. Note that specifying a global regular expression (i.e., with `g`) will allow independent linting of matched blocks within a single `@example`. * `rejectExampleCodeRegex` - Regex blacklist which rejects non-lintable examples (has priority over `exampleCodeRegex`). An example might be ```"^`"``` to avoid linting fenced blocks which may indicate a non-JavaScript language. See `exampleCodeRegex` on how to add flags if the default `u` is not sufficient. If neither is in use, all examples will be matched. Note also that even if `captionRequired` is not set, any initial `<caption>` will be stripped out before doing the regex matching. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-1-paddedindent"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-1-paddedindent"></a> ##### <code>paddedIndent</code> This integer property allows one to add a fixed amount of whitespace at the beginning of the second or later lines of the example to be stripped so as to avoid linting issues with the decorative whitespace. For example, if set to a value of `4`, the initial whitespace below will not trigger `indent` rule errors as the extra 4 spaces on each subsequent line will be stripped out before evaluation. ```js /** * @example * anArray.filter((a) => { * return a.b; * }); */ ``` Only applied to `@example` linting. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-1-reportunuseddisabledirectives"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-1-reportunuseddisabledirectives"></a> ##### <code>reportUnusedDisableDirectives</code> If not set to `false`, `reportUnusedDisableDirectives` will report disabled directives which are not used (and thus not needed). Defaults to `true`. Corresponds to ESLint's [`--report-unused-disable-directives`](https://eslint.org/docs/user-guide/command-line-interface#--report-unused-disable-directives). Inline ESLint config within `@example` JavaScript is allowed (or within `@default`, etc.), though the disabling of ESLint directives which are not needed by the resolved rules will be reported as with the ESLint `--report-unused-disable-directives` command. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig"></a> #### Options for Determining ESLint Rule Applicability (<code>allowInlineConfig</code>, <code>noDefaultExampleRules</code>, <code>matchingFileName</code>, <code>configFile</code>, <code>checkEslintrc</code>, and <code>baseConfig</code>) The following options determine which individual ESLint rules will be applied to the JavaScript found within the `@example` tags (as determined to be applicable by the above regex options) or for the other tags checked by `checkDefaults`, `checkParams`, or `checkProperties` options. They are ordered by decreasing precedence: * `allowInlineConfig` - If not set to `false`, will allow inline config within the `@example` to override other config. Defaults to `true`. * `noDefaultExampleRules` - Setting to `true` will disable the default rules which are expected to be troublesome for most documentation use. See the section below for the specific default rules. * `configFile` - A config file. Corresponds to ESLint's [`-c`](https://eslint.org/docs/user-guide/command-line-interface#-c---config). * `matchingFileName` - Option for a file name (even non-existent) to trigger specific rules defined in one's config; usable with ESLint `.eslintrc.*` `overrides` -> `files` globs, to apply a desired subset of rules with `@example` (besides allowing for rules specific to examples, this option can be useful for enabling reuse of the same rules within `@example` as with JavaScript Markdown lintable by [other plugins](https://github.com/eslint/eslint-plugin-markdown), e.g., if one sets `matchingFileName` to `dummy.md/*.js` so that `@example` rules will follow rules for fenced JavaScript blocks within one's Markdown rules). (In ESLint 6's processor API and `eslint-plugin-markdown` < 2, one would instead use `dummy.md`.) For `@example` only. * `matchingFileNameDefaults` - As with `matchingFileName` but for use with `checkDefaults` and defaulting to `.jsdoc-defaults` as extension. * `matchingFileNameParams` - As with `matchingFileName` but for use with `checkParams` and defaulting to `.jsdoc-params` as extension. * `matchingFileNameProperties` As with `matchingFileName` but for use with `checkProperties` and defaulting to `.jsdoc-properties` as extension. * `checkEslintrc` - Defaults to `true` in adding rules based on an `.eslintrc.*` file. Setting to `false` corresponds to ESLint's [`--no-eslintrc`](https://eslint.org/docs/user-guide/command-line-interface#--no-eslintrc). If `matchingFileName` is set, this will automatically be `true` and will use the config corresponding to that file. If `matchingFileName` is not set and this value is set to `false`, the `.eslintrc.*` configs will not be checked. If `matchingFileName` is not set, and this is unset or set to `true`, the `.eslintrc.*` configs will be checked as though the file name were the same as the file containing the example, with any file extension changed to `".md/*.js"` (and if there is no file extension, `"dummy.md/*.js"` will be the result). This allows convenient sharing of similar rules with often also context-free Markdown as well as use of `overrides` as described under `matchingFileName`. Note that this option (whether set by `matchingFileName` or set manually to `true`) may come at somewhat of a performance penalty as the file's existence is checked by eslint. * `baseConfig` - Set to an object of rules with the same schema as `.eslintrc.*` for defaults. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig-rules-disabled-by-default-unless-nodefaultexamplerules-is-set-to-true"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig-rules-disabled-by-default-unless-nodefaultexamplerules-is-set-to-true"></a> ##### Rules Disabled by Default Unless <code>noDefaultExampleRules</code> is Set to <code>true</code> * `eol-last` - Insisting that a newline "always" be at the end is less likely to be desired in sample code as with the code file convention. * `no-console` - This rule is unlikely to have inadvertent temporary debugging within examples. * `no-multiple-empty-lines` - This rule may be problematic for projects which use an initial newline just to start an example. Also, projects may wish to use extra lines within examples just for easier illustration purposes. * `no-undef` - Many variables in examples will be `undefined`. * `no-unused-vars` - It is common to define variables for clarity without always using them within examples. * `padded-blocks` - It can generally look nicer to pad a little even if one's code follows more stringency as far as block padding. * `jsdoc/require-file-overview` - Shouldn't check example for jsdoc blocks. * `jsdoc/require-jsdoc` - Wouldn't expect jsdoc blocks within jsdoc blocks. * `import/no-unresolved` - One wouldn't generally expect example paths to resolve relative to the current JavaScript file as one would with real code. * `import/unambiguous` - Snippets in examples are likely too short to always include full import/export info. * `node/no-missing-import` - See `import/no-unresolved`. * `node/no-missing-require` - See `import/no-unresolved`. For `checkDefaults`, `checkParams`, and `checkProperties`, the following expression-oriented rules will be used by default as well: * `quotes` - Will insist on "double". * `semi` - Will insist on "never". * `strict` - Disabled. * `no-empty-function` - Disabled. * `no-new` - Disabled. * `no-unused-expressions` - Disabled. * `chai-friendly/no-unused-expressions` - Disabled. <a name="user-content-eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig-options-for-checking-other-than-example-checkdefaults-checkparams-or-checkproperties"></a> <a name="eslint-plugin-jsdoc-rules-check-examples-options-for-determining-eslint-rule-applicability-allowinlineconfig-nodefaultexamplerules-matchingfilename-configfile-checkeslintrc-and-baseconfig-options-for-checking-other-than-example-checkdefaults-checkparams-or-checkproperties"></a> ##### Options for checking other than <code>@example</code> (<code>checkDefaults</code>, <code>checkParams</code>, or <code>checkProperties</code>) * `checkDefaults` - Whether to check the values of `@default`/`@defaultvalue` tags * `checkParams` - Whether to check `@param`/`@arg`/`@argument` default values * `checkProperties` - Whether to check `@property`/`@prop` default values ||| |---|---| |Context|everywhere| |Tags|`example`| |Recommended|false| |Options| *See above* | The following patterns are considered problems: ````js /** * @example alert('hello') */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"checkEslintrc":false}] // Message: @example error (no-alert): Unexpected alert. /** * @example alert('hello') */ class quux { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"no-alert":2,"semi":["error","always"]}},"checkEslintrc":false}] // Message: @example error (no-alert): Unexpected alert. /** * @example ```js alert('hello'); ``` */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}] // Message: @example error (semi): Extra semicolon. /** * @example * * ```js alert('hello'); ``` */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}] // Message: @example error (semi): Extra semicolon. /** * @example * ```js alert('hello'); ``` */ var quux = { }; // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js ([\\s\\S]*)```"}] // Message: @example error (semi): Extra semicolon. /** * @example ``` * js alert('hello'); ``` */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```\njs ([\\s\\S]*)```"}] // Message: @example error (semi): Extra semicolon. /** * @example <b>Not JavaScript</b> */ function quux () { } /** * @example quux2(); */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"rejectExampleCodeRegex":"^\\s*<.*>\\s*$"}] // Message: @example error (semi): Extra semicolon. /** * @example * quux(); // does something useful */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"no-undef":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":true}] // Message: @example error (no-undef): 'quux' is not defined. /** * @example <caption>Valid usage</caption> * quux(); // does something useful * * @example * quux('random unwanted arg'); // results in an error */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"captionRequired":true,"checkEslintrc":false}] // Message: Caption is expected for examples. /** * @example quux(); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] // Message: @example error (indent): Expected indentation of 0 spaces but found 1. /** * @example test() // eslint-disable-line semi */ function quux () {} // "jsdoc/check-examples": ["error"|"warn", {"checkEslintrc":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":true}] // Message: @example error: Unused eslint-disable directive (no problems were reported from 'semi'). /** * @example test() // eslint-disable-line semi */ function quux () {} // "jsdoc/check-examples": ["error"|"warn", {"allowInlineConfig":false,"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"noDefaultExampleRules":true}] // Message: @example error (semi): Missing semicolon. /** * @example const j = 5; * quux2(); */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"matchingFileName":"../../jsdocUtils.js"}] // Message: @example warning (id-length): Identifier name 'j' is too short (< 2). /** * @example const k = 5; * quux2(); */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"configFile":".eslintrc.json","matchingFileName":"../../jsdocUtils.js"}] // Message: @example warning (id-length): Identifier name 'k' is too short (< 2). /** * @example const m = 5; * quux2(); */ function quux2 () { } // Message: @example warning (id-length): Identifier name 'm' is too short (< 2). /** * @example const i = 5; * quux2() */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"paddedIndent":2}] // Message: @example warning (id-length): Identifier name 'i' is too short (< 2). /** * @example * const i = 5; * quux2() */ function quux2 () { } // Message: @example warning (id-length): Identifier name 'i' is too short (< 2). /** * @example const idx = 5; * quux2() */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"matchingFileName":"dummy.js"}] // Message: @example error (semi): Missing semicolon. /** * @example const idx = 5; * * quux2() */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"matchingFileName":"dummy.js"}] // Message: @example error (semi): Missing semicolon. /** * @example const idx = 5; * * quux2() */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"checkEslintrc":false,"matchingFileName":"dummy.js"}] // Message: @example error: Parsing error: The keyword 'const' is reserved /** * @example // begin alert('hello') // end */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["warn","always"]}},"checkEslintrc":false,"exampleCodeRegex":"// begin[\\s\\S]*// end","noDefaultExampleRules":true}] // Message: @example warning (semi): Missing semicolon. /** * @typedef {string} Foo * @example <caption></caption> * 'foo' */ // "jsdoc/check-examples": ["error"|"warn", {"captionRequired":true,"checkEslintrc":false}] // Message: Caption is expected for examples. /** * @example * const list: number[] = [1, 2, 3] * quux(list); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"parser":"@typescript-eslint/parser","parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}},"checkEslintrc":false}] // Message: @example error (semi): Missing semicolon. /** * @example * const test = something.find((_) => { * return _ * }); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}}}] // Message: @example error (semi): Missing semicolon. /** * @example <caption>Say `Hello!` to the user.</caption> * First, import the function: * * ```js * import popup from './popup' * const aConstInSameScope = 5; * ``` * * Then use it like this: * * ```js * const aConstInSameScope = 7; * popup('Hello!') * ``` * * Here is the result on macOS: * * ![Screenshot](path/to/screenshot.jpg) */ // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"parserOptions":{"ecmaVersion":2015,"sourceType":"module"},"rules":{"semi":["error","always"]}},"checkEslintrc":false,"exampleCodeRegex":"/^```(?:js|javascript)\\n([\\s\\S]*?)```$/gm"}] // Message: @example error (semi): Missing semicolon. /** * @example // begin alert('hello') // end * And here is another example: // begin alert('there') // end */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["warn","always"]}},"checkEslintrc":false,"exampleCodeRegex":"/\\/\\/ begin[\\s\\S]*?// end/g","noDefaultExampleRules":true}] // Message: @example warning (semi): Missing semicolon. /** * @example * quux(); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] // Message: @example error (indent): Expected indentation of 0 spaces but found 2. /** * @default 'abc' */ const str = 'abc'; // "jsdoc/check-examples": ["error"|"warn", {"checkDefaults":true}] // Message: @default error (quotes): Strings must use doublequote. /** * @param {myType} [name='abc'] */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"checkParams":true}] // Message: @param error (quotes): Strings must use doublequote. /** * @property {myType} [name='abc'] */ const obj = {}; // "jsdoc/check-examples": ["error"|"warn", {"checkProperties":true}] // Message: @property error (quotes): Strings must use doublequote. /** * Test function. * * @example <caption>functionName (paramOne: string, paramTwo?: any, * paramThree?: any): boolean</caption> test() * * @param {string} paramOne Parameter description. * @param {any} [paramTwo] Parameter description. * @param {any} [paramThree] Parameter description. * @returns {boolean} Return description. */ const functionName = function (paramOne, paramTwo, paramThree) { return false; }; // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"parserOptions":{"ecmaVersion":2015,"sourceType":"module"},"rules":{"semi":["error","always"]}},"captionRequired":true,"checkEslintrc":false}] // Message: @example error (semi): Missing semicolon. ```` The following patterns are not considered problems: ````js /** * @example ```js alert('hello'); ``` */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}] /** * @example ```js alert('hello'); ``` */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"exampleCodeRegex":"/```js([\\s\\S]*)```/"}] /** * @example * // arbitrary example content */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"checkEslintrc":false}] /** * @example * quux(); // does something useful */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"no-undef":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] /** * @example quux(); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] /** * @example <caption>Valid usage</caption> * quux(); // does something useful * * @example <caption>Invalid usage</caption> * quux('random unwanted arg'); // results in an error */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"captionRequired":true,"checkEslintrc":false}] /** * @example test() // eslint-disable-line semi */ function quux () {} // "jsdoc/check-examples": ["error"|"warn", {"checkEslintrc":false,"noDefaultExampleRules":true,"reportUnusedDisableDirectives":false}] /** * @example test() // eslint-disable-line semi */ function quux () {} // "jsdoc/check-examples": ["error"|"warn", {"allowInlineConfig":true,"baseConfig":{"rules":{"semi":["error","always"]}},"checkEslintrc":false,"noDefaultExampleRules":true}] /** * @example ```js alert('hello') ``` */ var quux = { }; // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"semi":["error","never"]}},"checkEslintrc":false,"exampleCodeRegex":"```js([\\s\\S]*)```"}] /** * @example * foo(function (err) { * throw err; * }); */ function quux () {} // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] /** * @example * const list: number[] = [1, 2, 3]; * quux(list); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"parser":"@typescript-eslint/parser","parserOptions":{"ecmaVersion":6},"rules":{"semi":["error","always"]}},"checkEslintrc":false}] /** * @example const ident = 5; * quux2(); * bar(); */ function quux2 () { } // "jsdoc/check-examples": ["error"|"warn", {"paddedIndent":2}] /** * @example * function quux() { * bar(); * } */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"rules":{"indent":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] // Comment a(); export default {}; /** * */ function f () { } /** * Does quux * @example * // Do it! * quux(); */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"plugins":["jsdoc"],"rules":{"jsdoc/require-file-overview":["error"]}},"checkEslintrc":false,"noDefaultExampleRules":false}] /** * @default "abc" */ const str = 'abc'; // "jsdoc/check-examples": ["error"|"warn", {"checkDefaults":true}] /** * @default */ const str = 'abc'; // "jsdoc/check-examples": ["error"|"warn", {"checkDefaults":true}] /** * @param {myType} [name="abc"] */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"checkParams":true}] /** * @param {myType} name */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"checkParams":true}] /** * @property {myType} [name="abc"] */ const obj = {}; // "jsdoc/check-examples": ["error"|"warn", {"checkProperties":true}] /** * @property {myType} [name] */ const obj = {}; // "jsdoc/check-examples": ["error"|"warn", {"checkProperties":true}] /** * @default 'abc' */ const str = 'abc'; // "jsdoc/check-examples": ["error"|"warn", {"checkDefaults":false,"matchingFileNameDefaults":"dummy.js"}] /** * @param {myType} [name='abc'] */ function quux () { } // "jsdoc/check-examples": ["error"|"warn", {"checkParams":false,"matchingFileNameParams":"dummy.js"}] /** * @property {myType} [name='abc'] */ const obj = {}; // "jsdoc/check-examples": ["error"|"warn", {"checkProperties":false,"matchingFileNameProperties":"dummy.js"}] /** * Test function. * * @example <caption>functionName (paramOne: string, paramTwo?: any, * paramThree?: any): boolean</caption> test(); * * @param {string} paramOne Parameter description. * @param {any} [paramTwo] Parameter description. * @param {any} [paramThree] Parameter description. * @returns {boolean} Return description. */ const functionName = function (paramOne, paramTwo, paramThree) { return false; }; // "jsdoc/check-examples": ["error"|"warn", {"baseConfig":{"parserOptions":{"ecmaVersion":2015,"sourceType":"module"},"rules":{"semi":["error","always"]}},"captionRequired":true,"checkEslintrc":false}] ```` <a name="user-content-eslint-plugin-jsdoc-rules-check-indentation"></a> <a name="eslint-plugin-jsdoc-rules-check-indentation"></a> ### <code>check-indentation</code> Reports invalid padding inside JSDoc blocks. Ignores parts enclosed in Markdown "code block"'s. For example, the following description is not reported: ```js /** * Some description: * ```html * <section> * <title>test</title> * </section> * ``` */ ``` <a name="user-content-eslint-plugin-jsdoc-rules-check-indentation-options-2"></a> <a name="eslint-plugin-jsdoc-rules-check-indentation-options-2"></a> #### Options This rule has an object option. <a name="user-content-eslint-plugin-jsdoc-rules-check-indentation-options-2-excludetags"></a> <a name="eslint-plugin-jsdoc-rules-check-indentation-options-2-excludetags"></a> ##### <code>excludeTags</code> Array of tags (e.g., `['example', 'description']`) whose content will be "hidden" from the `check-indentation` rule. Defaults to `['example']`. By default, the whole JSDoc block will be checked for invalid padding. That would include `@example` blocks too, which can get in the way of adding full, readable examples of code without ending up with multiple linting issues. When disabled (by passing `excludeTags: []` option), the following code *will* report a padding issue: ```js /** * @example * anArray.f


نیازمندی

مقدار نام
~0.37.0 @es-joy/jsdoccomment
^0.0.2 are-docs-informative
1.3.1 comment-parser
^4.3.4 debug
^4.0.0 escape-string-regexp
^1.5.0 esquery
^7.3.8 semver
^3.0.1 spdx-expression-parse


زبان مورد نیاز

مقدار نام
18.15.0 Npm


نحوه نصب


نصب پکیج tgz eslint-plugin-jsdoc-41.1.1:

    npm install eslint-plugin-jsdoc-41.1.1.tgz