diff --git a/packages/eslint-plugin/docs/rules/ban-ts-comment.mdx b/packages/eslint-plugin/docs/rules/ban-ts-comment.mdx index 8f287665a3ce..e2338747b707 100644 --- a/packages/eslint-plugin/docs/rules/ban-ts-comment.mdx +++ b/packages/eslint-plugin/docs/rules/ban-ts-comment.mdx @@ -97,6 +97,8 @@ if (false) { ### `descriptionFormat` +{/* insert option description */} + For each directive type, you can specify a custom format in the form of a regular expression. Only description that matches the pattern will be allowed. For example, with `{ 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }`: @@ -124,6 +126,8 @@ const a = doSomething('hello'); ### `minimumDescriptionLength` +{/* insert option description */} + Use `minimumDescriptionLength` to set a minimum length for descriptions when using the `allow-with-description` option for a directive. For example, with `{ 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 }` the following pattern is: diff --git a/packages/eslint-plugin/docs/rules/class-methods-use-this.mdx b/packages/eslint-plugin/docs/rules/class-methods-use-this.mdx index dc48c04227bc..7023306a183c 100644 --- a/packages/eslint-plugin/docs/rules/class-methods-use-this.mdx +++ b/packages/eslint-plugin/docs/rules/class-methods-use-this.mdx @@ -31,6 +31,8 @@ const defaultOptions: Options = { ### `ignoreOverrideMethods` +{/* insert option description */} + Makes the rule ignore any class member explicitly marked with `override`. Example of a correct code when `ignoreOverrideMethods` is set to `true`: @@ -44,7 +46,8 @@ class X { ### `ignoreClassesThatImplementAnInterface` -Makes the rule ignore class members that are defined within a class that `implements` a type. +{/* insert option description */} + If specified, it can be either: - `true`: Ignore all classes that implement an interface diff --git a/packages/eslint-plugin/docs/rules/consistent-generic-constructors.mdx b/packages/eslint-plugin/docs/rules/consistent-generic-constructors.mdx index 486147a04551..e4c5e0708398 100644 --- a/packages/eslint-plugin/docs/rules/consistent-generic-constructors.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-generic-constructors.mdx @@ -27,10 +27,12 @@ Keeping to one side consistently improve code readability. ## Options -- `constructor` _(default)_: type arguments that **only** appear on the type annotation are disallowed. -- `type-annotation`: type arguments that **only** appear on the constructor are disallowed. +- `'constructor'` _(default)_: type arguments that **only** appear on the type annotation are disallowed. +- `'type-annotation'`: type arguments that **only** appear on the constructor are disallowed. -### `constructor` +### `'constructor'` + +{/* insert option description */} @@ -54,7 +56,7 @@ const set: Set = new Set(); -### `type-annotation` +### `'type-annotation'` diff --git a/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.mdx b/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.mdx index 7ac21461479b..8aeb34e238d5 100644 --- a/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-indexed-object-style.mdx @@ -27,10 +27,12 @@ Using one declaration form consistently improves code readability. ## Options -- `"record"` _(default)_: only allow the `Record` type. -- `"index-signature"`: only allow index signatures. +- `'record'` _(default)_: only allow the `Record` type. +- `'index-signature'`: only allow index signatures. -### `record` +### `'record'` + +{/* insert option description */} @@ -55,7 +57,7 @@ type Foo = Record; -### `index-signature` +### `'index-signature'` diff --git a/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx b/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx index cf437b9ed714..0b13d9df2677 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-assertions.mdx @@ -30,7 +30,9 @@ Examples of them include `let x = "hello" as const;` and `let x = "hello" ### `assertionStyle` -The expected assertion style to enforce. Valid values for `assertionStyle` are: +{/* insert option description */} + +Valid values for `assertionStyle` are: - `as` will enforce that you always use `... as foo`. - `angle-bracket` will enforce that you always use `...` @@ -42,7 +44,7 @@ Some codebases like to go for an extra level of type safety, and ban assertions ### `objectLiteralTypeAssertions` -Whether to always prefer type declarations for object literals used as variable initializers, rather than type assertions. +{/* insert option description */} For example, this would prefer `const x: T = { ... };` to `const x = { ... } as T;` (or similar with angle brackets). The type assertion in the latter case is either unnecessary or will probably hide an error. diff --git a/packages/eslint-plugin/docs/rules/consistent-type-definitions.mdx b/packages/eslint-plugin/docs/rules/consistent-type-definitions.mdx index 353bd1cf6258..68060f551a3b 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-definitions.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-definitions.mdx @@ -30,10 +30,12 @@ Using the same type declaration style consistently helps with code readability. ## Options -- `"interface"` _(default)_: enforce using `interface`s for object type definitions. -- `"type"`: enforce using `type`s for object type definitions. +- `'interface'` _(default)_: enforce using `interface`s for object type definitions. +- `'type'`: enforce using `type`s for object type definitions. -### `interface` +### `'interface'` + +{/* insert option description */} @@ -57,7 +59,9 @@ interface T { -### `type` +### `'type'` + +{/* insert option description */} diff --git a/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx b/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx index 7c2ed45dcda9..293db56fd5f0 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-exports.mdx @@ -54,7 +54,8 @@ export type { ButtonProps }; ### `fixMixedExportsWithInlineTypeSpecifier` -Whether the rule will autofix "mixed" export cases using TS inline type specifiers. +{/* insert option description */} + If you are using a TypeScript version less than 4.5, then you will not be able to use this option. For example the following code: diff --git a/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx b/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx index cacc53d50a2c..3f7dc32004e0 100644 --- a/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx +++ b/packages/eslint-plugin/docs/rules/consistent-type-imports.mdx @@ -18,7 +18,9 @@ This allows transpilers to drop imports without knowing the types of the depende ### `prefer` -The expected import kind for type-only imports. Valid values for `prefer` are: +{/* insert option description */} + +Valid values for `prefer` are: - `type-imports` will enforce that you always use `import type Foo from '...'` except referenced by metadata of decorators. It is the default. - `no-type-imports` will enforce that you always use `import Foo from '...'`. @@ -43,7 +45,9 @@ const x: Bar = 1; ### `fixStyle` -The expected type modifier to be added when an import is detected as used only in the type position. Valid values for `fixStyle` are: +{/* insert option description */} + +Valid values for `fixStyle` are: - `separate-type-imports` will add the type keyword after the import keyword `import type { A } from '...'`. It is the default. - `inline-type-imports` will inline the type keyword `import { type A } from '...'` and is only available in TypeScript 4.5 and onwards. See [documentation here](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names 'TypeScript 4.5 documentation on type modifiers and import names'). @@ -83,8 +87,7 @@ const x: Bar = 1; ### `disallowTypeAnnotations` -Whether to disallow type imports in type annotations (`import()`). -Default is `true`. +{/* insert option description */} Examples of **incorrect** code with `{disallowTypeAnnotations: true}`: diff --git a/packages/eslint-plugin/docs/rules/dot-notation.mdx b/packages/eslint-plugin/docs/rules/dot-notation.mdx index cf44c44028b8..fd6967f947e0 100644 --- a/packages/eslint-plugin/docs/rules/dot-notation.mdx +++ b/packages/eslint-plugin/docs/rules/dot-notation.mdx @@ -38,7 +38,8 @@ If the TypeScript compiler option `noPropertyAccessFromIndexSignature` is set to ### `allowPrivateClassPropertyAccess` -Whether to allow accessing class members marked as `private` with array notation. +{/* insert option description */} + This can be useful because TypeScript will report a type error on dot notation but not array notation. Example of a correct code when `allowPrivateClassPropertyAccess` is set to `true`: @@ -54,7 +55,8 @@ x['priv_prop'] = 123; ### `allowProtectedClassPropertyAccess` -Whether to allow accessing class members marked as `protected` with array notation. +{/* insert option description */} + This can be useful because TypeScript will report a type error on dot notation but not array notation. Example of a correct code when `allowProtectedClassPropertyAccess` is set to `true`: @@ -70,7 +72,7 @@ x['protected_prop'] = 123; ### `allowIndexSignaturePropertyAccess` -Whether to allow accessing properties matching an index signature with array notation. +{/* insert option description */} Example of correct code when `allowIndexSignaturePropertyAccess` is set to `true`: diff --git a/packages/eslint-plugin/docs/rules/explicit-function-return-type.mdx b/packages/eslint-plugin/docs/rules/explicit-function-return-type.mdx index f664314cd462..1bc1a56e50e6 100644 --- a/packages/eslint-plugin/docs/rules/explicit-function-return-type.mdx +++ b/packages/eslint-plugin/docs/rules/explicit-function-return-type.mdx @@ -98,6 +98,8 @@ If you are working on a codebase within which you lint non-TypeScript code (i.e. ### `allowExpressions` +{/* insert option description */} + Examples of code for this rule with `{ allowExpressions: true }`: @@ -127,6 +129,8 @@ const foo = arr.map(i => i * i); ### `allowTypedFunctionExpressions` +{/* insert option description */} + Examples of code for this rule with `{ allowTypedFunctionExpressions: true }`: @@ -188,6 +192,8 @@ functionWithObjectArg({ ### `allowHigherOrderFunctions` +{/* insert option description */} + Examples of code for this rule with `{ allowHigherOrderFunctions: true }`: @@ -217,6 +223,8 @@ function fn() { ### `allowDirectConstAssertionInArrowFunctions` +{/* insert option description */} + Examples of code for this rule with `{ allowDirectConstAssertionInArrowFunctions: true }`: @@ -240,6 +248,8 @@ const func = () => x as const; ### `allowConciseArrowFunctionExpressionsStartingWithVoid` +{/* insert option description */} + Examples of code for this rule with `{ allowConciseArrowFunctionExpressionsStartingWithVoid: true }`: @@ -265,6 +275,8 @@ var log = (message: string) => void console.log(message); ### `allowFunctionsWithoutTypeParameters` +{/* insert option description */} + Examples of code for this rule with `{ allowFunctionsWithoutTypeParameters: true }`: @@ -300,6 +312,8 @@ const allowedArrow = (x: string) => x; ### `allowedNames` +{/* insert option description */} + You may pass function/method names you would like this rule to ignore, like so: ```json @@ -315,6 +329,8 @@ You may pass function/method names you would like this rule to ignore, like so: ### `allowIIFEs` +{/* insert option description */} + Examples of code for this rule with `{ allowIIFEs: true }`: diff --git a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx index 60f4f6c2a810..67b78cbed113 100644 --- a/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx +++ b/packages/eslint-plugin/docs/rules/explicit-member-accessibility.mdx @@ -49,6 +49,8 @@ If you are working on a codebase within which you lint non-TypeScript code (i.e. ### `accessibility` +{/* insert option description */} + This rule in its default state requires no configuration and will enforce that every class member has an accessibility modifier. If you would like to allow for some implicit public members then you have the following options: ```jsonc @@ -169,6 +171,8 @@ class Animal { ### `overrides` +{/* insert option description */} + There are three ways in which an override can be used. - To disallow the use of public on a given member. @@ -317,8 +321,9 @@ class Animal { ### `ignoredMethodNames` -Specific method names that may be ignored. -Note that this option does not care for the context, and will ignore every method with these names, which could lead to it missing some cases. You should use this sparingly. +{/* insert option description */} + +Note that this option does not care about context, and will ignore every method with these names, which could lead to it missing some cases. You should use this sparingly. e.g. `[ { ignoredMethodNames: ['specificMethod', 'whateverMethod'] } ]` ```ts option='{ "ignoredMethodNames": ["specificMethod", "whateverMethod"] }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx index 7a19ab87c726..fadbfa296975 100644 --- a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx +++ b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.mdx @@ -97,17 +97,19 @@ If you are working on a codebase within which you lint non-TypeScript code (i.e. ### `allowArgumentsExplicitlyTypedAsAny` -When this option is `true`, the rule ignores arguments that are explicitly typed as any. +{/* insert option description */} + +Examples of code for this rule with `{ allowArgumentsExplicitlyTypedAsAny: false }`: - + ```ts option='{ "allowArgumentsExplicitlyTypedAsAny": false }' export const func = (value: any): number => value + 1; ``` - + ```ts option='{ "allowArgumentsExplicitlyTypedAsAny": true }' export const func = (value: any): number => value + 1; @@ -118,10 +120,12 @@ export const func = (value: any): number => value + 1; ### `allowDirectConstAssertionInArrowFunctions` -When this option is `true`, the rule ignores return type annotations on body-less arrow functions that return an `as const` type assertion. +{/* insert option description */} + +Examples of code for this rule with `{ allowDirectConstAssertionInArrowFunctions: false }`: - + ```ts option='{ "allowDirectConstAssertionInArrowFunctions": false }' export const func = (value: number) => ({ type: 'X', value }); @@ -132,7 +136,7 @@ export const bar = () => 1; ``` - + ```ts option='{ "allowDirectConstAssertionInArrowFunctions": true }' export const func = (value: number) => ({ type: 'X', value }) as const; @@ -148,6 +152,8 @@ export const bar = () => 1 as const; ### `allowedNames` +{/* insert option description */} + You may pass function/method names you would like this rule to ignore, like so: ```json @@ -163,10 +169,12 @@ You may pass function/method names you would like this rule to ignore, like so: ### `allowHigherOrderFunctions` -When this option is `true`, the rule ignores return type annotations on function, which is immediately returning another function expression. +{/* insert option description */} + +Examples of code for this rule with `{ allowHigherOrderFunctions: false }`: - + ```ts option='{ "allowHigherOrderFunctions": false }' export const arrowFn = () => () => {}; @@ -181,7 +189,7 @@ export function foo(outer: string) { ``` - + ```ts option='{ "allowHigherOrderFunctions": true }' export const arrowFn = () => (): void => {}; @@ -200,10 +208,12 @@ export function foo(outer: string) { ### `allowTypedFunctionExpressions` -When this option is `true`, the rule ignores type annotations on the variable of a function expression. +{/* insert option description */} + +Examples of code for this rule with `{ allowTypedFunctionExpressions: false }`: - + ```ts option='{ "allowTypedFunctionExpressions": false }' export let arrowFn = () => 'test'; @@ -220,7 +230,7 @@ export const foo = bar => {}; ``` - + ```ts option='{ "allowTypedFunctionExpressions": true }' type FuncType = () => string; diff --git a/packages/eslint-plugin/docs/rules/max-params.mdx b/packages/eslint-plugin/docs/rules/max-params.mdx index 1797dffaec73..d1a363734000 100644 --- a/packages/eslint-plugin/docs/rules/max-params.mdx +++ b/packages/eslint-plugin/docs/rules/max-params.mdx @@ -29,7 +29,7 @@ const defaultOptions: Options = { ### `countVoidThis` -Whether to count a `this` declaration when the type is `void`. +{/* insert option description */} Example of a code when `countVoidThis` is set to `false` and `max` is `1`: diff --git a/packages/eslint-plugin/docs/rules/method-signature-style.mdx b/packages/eslint-plugin/docs/rules/method-signature-style.mdx index 0536bff803a5..1f2696276b9c 100644 --- a/packages/eslint-plugin/docs/rules/method-signature-style.mdx +++ b/packages/eslint-plugin/docs/rules/method-signature-style.mdx @@ -39,10 +39,10 @@ This rule accepts one string option: - `"property"`: Enforce using property signature for functions. Use this to enforce maximum correctness together with TypeScript's strict mode. - `"method"`: Enforce using method signature for functions. Use this if you aren't using TypeScript's strict mode and prefer this style. -The default is `"property"`. - ### `property` +{/* insert option description */} + Examples of code with `property` option. @@ -85,6 +85,8 @@ interface T3 { ### `method` +{/* insert option description */} + Examples of code with `method` option. diff --git a/packages/eslint-plugin/docs/rules/no-base-to-string.mdx b/packages/eslint-plugin/docs/rules/no-base-to-string.mdx index 97767da415b8..f2bf27b8e072 100644 --- a/packages/eslint-plugin/docs/rules/no-base-to-string.mdx +++ b/packages/eslint-plugin/docs/rules/no-base-to-string.mdx @@ -66,9 +66,10 @@ const literalWithToString = { ### `ignoredTypeNames` -Stringified regular expressions of type names to ignore. -This is useful for types missing `toString()` (but actually has `toString()`). -There are some types missing `toString()` in old version TypeScript, like `RegExp`, `URL`, `URLSearchParams` etc. +{/* insert option description */} + +This is useful for types whose declarations missing `toString()`, but are known to actually have `toString()`. +There are some types missing `toString()` in TypeScript, like `RegExp`, `URL`, `URLSearchParams` etc. The following patterns are considered correct with the default options `{ ignoredTypeNames: ["RegExp"] }`: @@ -93,3 +94,4 @@ If you don't mind a risk of `"[object Object]"` or incorrect type coercions in y ## Further Reading - [`Object.prototype.toString()` MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) +- [Microsoft/TypeScript Add missing toString declarations for base types that have them](https://github.com/microsoft/TypeScript/issues/38347) diff --git a/packages/eslint-plugin/docs/rules/no-confusing-void-expression.mdx b/packages/eslint-plugin/docs/rules/no-confusing-void-expression.mdx index b779558319b7..15c2815ac19c 100644 --- a/packages/eslint-plugin/docs/rules/no-confusing-void-expression.mdx +++ b/packages/eslint-plugin/docs/rules/no-confusing-void-expression.mdx @@ -77,6 +77,8 @@ cond ? console.log('true') : console.error('false'); ### `ignoreArrowShorthand` +{/* insert option description */} + Whether to ignore "shorthand" `() =>` arrow functions: those without `{ ... }` braces. It might be undesirable to wrap every arrow function shorthand expression. @@ -90,6 +92,8 @@ promise.then(value => window.postMessage(value)); ### `ignoreVoidOperator` +{/* insert option description */} + Whether to ignore returns that start with the `void` operator. It might be preferable to only use some distinct syntax diff --git a/packages/eslint-plugin/docs/rules/no-duplicate-type-constituents.mdx b/packages/eslint-plugin/docs/rules/no-duplicate-type-constituents.mdx index 37a1e36e6217..dfd7d2d435ec 100644 --- a/packages/eslint-plugin/docs/rules/no-duplicate-type-constituents.mdx +++ b/packages/eslint-plugin/docs/rules/no-duplicate-type-constituents.mdx @@ -67,10 +67,14 @@ const fn = (a?: string) => {}; ### `ignoreIntersections` +{/* insert option description */} + When set to true, duplicate checks on intersection type constituents are ignored. ### `ignoreUnions` +{/* insert option description */} + When set to true, duplicate checks on union type constituents are ignored. ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-empty-interface.mdx b/packages/eslint-plugin/docs/rules/no-empty-interface.mdx index 733d8b39ebe6..4eeb2f3247ec 100644 --- a/packages/eslint-plugin/docs/rules/no-empty-interface.mdx +++ b/packages/eslint-plugin/docs/rules/no-empty-interface.mdx @@ -62,7 +62,9 @@ interface Baz extends Foo, Bar {} ### `allowSingleExtends` -`allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members +{/* insert option description */} + +`allowSingleExtends: true` will silence warnings about extending a single interface without adding additional members. ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx b/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx index 8bf941a66615..b1ed390ad9f0 100644 --- a/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx +++ b/packages/eslint-plugin/docs/rules/no-empty-object-type.mdx @@ -83,7 +83,9 @@ By default, this rule flags both interfaces and object types. ### `allowInterfaces` -Whether to allow empty interfaces, as one of: +{/* insert option description */} + +Allowed values are: - `'always'`: to always allow interfaces with no fields - `'never'` _(default)_: to never allow interfaces with no fields @@ -101,14 +103,17 @@ interface Derived extends Base {} ### `allowObjectTypes` -Whether to allow empty object type literals, as one of: +{/* insert option description */} + +Allowed values are: - `'always'`: to always allow object type literals with no fields - `'never'` _(default)_: to never allow object type literals with no fields ### `allowWithName` -A stringified regular expression to allow interfaces and object type aliases with the configured name. +{/* insert option description */} + This can be useful if your existing code style includes a pattern of declaring empty types with `{}` instead of `object`. Examples of code for this rule with `{ allowWithName: 'Props$' }`: diff --git a/packages/eslint-plugin/docs/rules/no-explicit-any.mdx b/packages/eslint-plugin/docs/rules/no-explicit-any.mdx index 52f7108d165b..33b382920bc1 100644 --- a/packages/eslint-plugin/docs/rules/no-explicit-any.mdx +++ b/packages/eslint-plugin/docs/rules/no-explicit-any.mdx @@ -107,6 +107,8 @@ function greet(param: Array): Array {} ### `fixToUnknown` +{/* insert option description */} + By default, this rule will not provide automatic ESLint _fixes_: only opt-in _suggestions_. Switching types to `unknown` is safer but is likely to cause additional type errors. @@ -114,7 +116,7 @@ Enabling `{ "fixToUnknown": true }` gives the rule an auto-fixer to replace `: a ### `ignoreRestArgs` -A boolean to specify if arrays from the rest operator are considered okay. `false` by default. +{/* insert option description */} The examples below are **incorrect** when `{ignoreRestArgs: false}`, but **correct** when `{ignoreRestArgs: true}`. diff --git a/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx b/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx index 0966be0978c1..b6639b5ab85c 100644 --- a/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx +++ b/packages/eslint-plugin/docs/rules/no-extraneous-class.mdx @@ -221,7 +221,7 @@ The rule's options each add an exemption for a specific type of class. ### `allowConstructorOnly` -`allowConstructorOnly` adds an exemption for classes that have only a constructor and no fields. +{/* insert option description */} @@ -246,7 +246,7 @@ class NoFields { ### `allowEmpty` -The `allowEmpty` option adds an exemption for classes that are entirely empty. +{/* insert option description */} @@ -271,7 +271,7 @@ class NoFields {} ### `allowStaticOnly` -The `allowStaticOnly` option adds an exemption for classes that only contain static members. +{/* insert option description */} :::caution We strongly recommend against the `allowStaticOnly` exemption. @@ -299,7 +299,7 @@ class NotEmptyClass { ### `allowWithDecorator` -The `allowWithDecorator` option adds an exemption for classes decorated with a `@` decorator. +{/* insert option description */} diff --git a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx index 355fe6aeb141..12bf7465b537 100644 --- a/packages/eslint-plugin/docs/rules/no-floating-promises.mdx +++ b/packages/eslint-plugin/docs/rules/no-floating-promises.mdx @@ -87,6 +87,8 @@ await Promise.all([1, 2, 3].map(async x => x + 1)); ### `checkThenables` +{/* insert option description */} + A ["Thenable"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables) value is an object which has a `then` method, such as a `Promise`. Other Thenables include TypeScript's built-in `PromiseLike` interface and any custom object that happens to have a `.then()`. @@ -132,8 +134,9 @@ await createMyThenable(); ### `ignoreVoid` -This option, which is `true` by default, allows you to stop the rule reporting promises consumed with the [`void` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/void). -This can be a good way to explicitly mark a promise as intentionally not awaited. +{/* insert option description */} + +Placing the [`void` operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/void) in front of a Promise can be a convenient way to explicitly mark that Promise as intentionally not awaited. :::warning Voiding a Promise doesn't handle it or change the runtime behavior. @@ -152,11 +155,11 @@ void returnsPromise(); void Promise.reject('value'); ``` -With this option set to `true`, and if you are using `no-void`, you should turn on the [`allowAsStatement`](https://eslint.org/docs/rules/no-void#allowasstatement) option. +When this option is set to `true`, if you are using `no-void`, you should turn on the [`allowAsStatement`](https://eslint.org/docs/rules/no-void#allowasstatement) option. ### `ignoreIIFE` -This allows you to skip checking of async IIFEs (Immediately Invoked Function Expressions). +{/* insert option description */} Examples of **correct** code for this rule with `{ ignoreIIFE: true }`: @@ -173,7 +176,9 @@ await (async function () { ### `allowForKnownSafePromises` -Specific types to be marked as "safe" to be floating. For example, you may need to do this in the case of libraries whose APIs return Promises whose rejections are safely handled by the library. +{/* insert option description */} + +For example, you may need to do this in the case of libraries whose APIs return Promises whose rejections are safely handled by the library. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). @@ -225,7 +230,8 @@ returnsSafePromise(); ### `allowForKnownSafeCalls` -Specific functions to be marked as "safe" to be called to create floating Promises. +{/* insert option description */} + For example, you may need to do this in the case of libraries whose APIs may be called without handling the resultant Promises. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). diff --git a/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx b/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx index 1bddfeb3c249..25bfbbec04ce 100644 --- a/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx +++ b/packages/eslint-plugin/docs/rules/no-inferrable-types.mdx @@ -80,7 +80,7 @@ function fn(a = 5, b = true) {} ### `ignoreParameters` -Whether to ignore function parameters. +{/* insert option description */} When set to true, the following pattern is considered valid: @@ -92,7 +92,7 @@ function foo(a: number = 5, b: boolean = true) { ### `ignoreProperties` -Whether to ignore class properties. +{/* insert option description */} When set to true, the following pattern is considered valid: diff --git a/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx b/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx index 1e6a1507a3fa..6cfa270680a8 100644 --- a/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx +++ b/packages/eslint-plugin/docs/rules/no-invalid-void-type.mdx @@ -62,9 +62,9 @@ type stillVoid = void | never; ### `allowInGenericTypeArguments` -Whether `void` can be used as a valid value for generic type parameters. +{/* insert option description */} -Alternatively, you can provide an array of strings which whitelist which types may accept `void` as a generic type parameter. +Alternatively, you can provide an array of strings which allowlist which types may accept `void` as a generic type parameter. Any types considered valid by this option will be considered valid as part of a union type with `void`. @@ -98,7 +98,8 @@ type AllowedVoidUnion = void | Ex.Mx.Tx; ### `allowAsThisParameter` -Whether a `this` parameter of a function may be `void`. +{/* insert option description */} + This pattern can be useful to explicitly label function types that do not use a `this` argument. [See the TypeScript docs for more information](https://www.typescriptlang.org/docs/handbook/functions.html#this-parameters-in-callbacks). This option is `false` by default. diff --git a/packages/eslint-plugin/docs/rules/no-magic-numbers.mdx b/packages/eslint-plugin/docs/rules/no-magic-numbers.mdx index 2110f5bed847..09f07b945a1f 100644 --- a/packages/eslint-plugin/docs/rules/no-magic-numbers.mdx +++ b/packages/eslint-plugin/docs/rules/no-magic-numbers.mdx @@ -39,6 +39,8 @@ const defaultOptions: Options = { ### `ignoreEnums` +{/* insert option description */} + Whether enums used in TypeScript are considered okay. `false` by default. Examples of **incorrect** code for the `{ "ignoreEnums": false }` option: @@ -59,6 +61,8 @@ enum foo { ### `ignoreNumericLiteralTypes` +{/* insert option description */} + Whether numbers used in TypeScript numeric literal types are considered okay. `false` by default. Examples of **incorrect** code for the `{ "ignoreNumericLiteralTypes": false }` option: @@ -75,6 +79,8 @@ type SmallPrimes = 2 | 3 | 5 | 7 | 11; ### `ignoreReadonlyClassProperties` +{/* insert option description */} + Whether `readonly` class properties are considered okay. Examples of **incorrect** code for the `{ "ignoreReadonlyClassProperties": false }` option: @@ -101,6 +107,8 @@ class Foo { ### `ignoreTypeIndexes` +{/* insert option description */} + Whether numbers used to index types are okay. `false` by default. Examples of **incorrect** code for the `{ "ignoreTypeIndexes": false }` option: diff --git a/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx b/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx index 518da46b3328..c4987ea2a4d3 100644 --- a/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx +++ b/packages/eslint-plugin/docs/rules/no-meaningless-void-operator.mdx @@ -54,7 +54,7 @@ void bar(1); // discarding a number ### `checkNever` -Whether to suggest removing `void` when the argument has type `never`. +{/* insert option description */} ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/no-misused-promises.mdx b/packages/eslint-plugin/docs/rules/no-misused-promises.mdx index f4fd23fec126..52dc08dfcef6 100644 --- a/packages/eslint-plugin/docs/rules/no-misused-promises.mdx +++ b/packages/eslint-plugin/docs/rules/no-misused-promises.mdx @@ -22,6 +22,8 @@ See [`no-floating-promises`](./no-floating-promises.mdx) for detecting unhandled ### `checksConditionals` +{/* insert option description */} + If you don't want to check conditionals, you can configure the rule with `"checksConditionals": false`: ```json @@ -39,6 +41,8 @@ Doing so prevents the rule from looking at code like `if (somePromise)`. ### `checksVoidReturn` +{/* insert option description */} + Likewise, if you don't want to check functions that return promises where a void return is expected, your configuration will look like this: @@ -101,7 +105,7 @@ Disables checking an asynchronous function used as a variable whose return type ### `checksSpreads` -Whether to warn when `...` spreading a `Promise`. +{/* insert option description */} If you don't want to check object spreads, you can add this configuration: @@ -120,6 +124,8 @@ If you don't want to check object spreads, you can add this configuration: ### `checksConditionals` +{/* insert option description */} + Examples of code for this rule with `checksConditionals: true`: @@ -167,6 +173,8 @@ while (await promise) { ### `checksVoidReturn` +{/* insert option description */} + Examples of code for this rule with `checksVoidReturn: true`: @@ -254,6 +262,8 @@ class MyClass implements MyAsyncInterface { ### `checksSpreads` +{/* insert option description */} + Examples of code for this rule with `checksSpreads: true`: diff --git a/packages/eslint-plugin/docs/rules/no-namespace.mdx b/packages/eslint-plugin/docs/rules/no-namespace.mdx index 3bb12bf375ae..8e7ca864a8f7 100644 --- a/packages/eslint-plugin/docs/rules/no-namespace.mdx +++ b/packages/eslint-plugin/docs/rules/no-namespace.mdx @@ -46,6 +46,8 @@ declare module 'foo' {} ### `allowDeclarations` +{/* insert option description */} + Examples of code with the `{ "allowDeclarations": true }` option: @@ -100,6 +102,8 @@ declare module 'foo' {} ### `allowDefinitionFiles` +{/* insert option description */} + Examples of code for the `{ "allowDefinitionFiles": true }` option: diff --git a/packages/eslint-plugin/docs/rules/no-redeclare.mdx b/packages/eslint-plugin/docs/rules/no-redeclare.mdx index e4cf6d6df98c..8b24af9797ee 100644 --- a/packages/eslint-plugin/docs/rules/no-redeclare.mdx +++ b/packages/eslint-plugin/docs/rules/no-redeclare.mdx @@ -33,7 +33,9 @@ const defaultOptions: Options = { ### `ignoreDeclarationMerge` -Whether to ignore declaration merges between the following sets: +{/* insert option description */} + +The following sets will be ignored when this option is enabled: - interface + interface - namespace + namespace diff --git a/packages/eslint-plugin/docs/rules/no-require-imports.mdx b/packages/eslint-plugin/docs/rules/no-require-imports.mdx index 4512c2693d95..1d4fd9ea7bb7 100644 --- a/packages/eslint-plugin/docs/rules/no-require-imports.mdx +++ b/packages/eslint-plugin/docs/rules/no-require-imports.mdx @@ -38,7 +38,9 @@ import * as lib3 from 'lib3'; ### `allow` -An array of strings. These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work. +{/* insert option description */} + +These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work. With `{allow: ['/package\\.json$']}`: @@ -61,7 +63,9 @@ console.log(require('../package.json').version); ### `allowAsImport` -When set to `true`, the `import x = require(...)` declaration won't be reported. +{/* insert option description */} + +When set to `true`, `import ... = require(...)` declarations won't be reported. This is useful if you use certain module options that require strict CommonJS interop semantics. With `{allowAsImport: true}`: diff --git a/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx b/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx index 621bf351e833..2c42980c4e0d 100644 --- a/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx +++ b/packages/eslint-plugin/docs/rules/no-restricted-imports.mdx @@ -17,7 +17,10 @@ This rule adds the following options: ### `allowTypeImports` -(default: `false`) +{/* insert option description */} + +Whether to allow type-only imports for a path. +Default: `false`. You can specify this option for a specific path or pattern as follows: diff --git a/packages/eslint-plugin/docs/rules/no-restricted-types.mdx b/packages/eslint-plugin/docs/rules/no-restricted-types.mdx index 20732174929e..40219e99e39d 100644 --- a/packages/eslint-plugin/docs/rules/no-restricted-types.mdx +++ b/packages/eslint-plugin/docs/rules/no-restricted-types.mdx @@ -19,7 +19,7 @@ Note that it does not ban the corresponding runtime objects from being used. ### `types` -An object whose keys are the types you want to ban, and the values are error messages. +{/* insert option description */} The type can either be a type name literal (`OldType`) or a a type name with generic parameter instantiation(s) (`OldType`). diff --git a/packages/eslint-plugin/docs/rules/no-shadow.mdx b/packages/eslint-plugin/docs/rules/no-shadow.mdx index 40651e2fbe99..ecd105f6e334 100644 --- a/packages/eslint-plugin/docs/rules/no-shadow.mdx +++ b/packages/eslint-plugin/docs/rules/no-shadow.mdx @@ -31,7 +31,9 @@ const defaultOptions: Options = { ### `ignoreTypeValueShadow` -Whether to ignore types named the same as a variable. This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion. +{/* insert option description */} + +This is generally safe because you cannot use variables in type locations without a `typeof` operator, so there's little risk of confusion. Examples of **correct** code with `{ ignoreTypeValueShadow: true }`: @@ -55,7 +57,7 @@ _Shadowing_ specifically refers to two identical identifiers that are in differe ### `ignoreFunctionTypeParameterNameValueShadow` -Whether to ignore function parameters named the same as a variable. +{/* insert option description */} Each of a function type's arguments creates a value variable within the scope of the function type. This is done so that you can reference the type later using the `typeof` operator: diff --git a/packages/eslint-plugin/docs/rules/no-this-alias.mdx b/packages/eslint-plugin/docs/rules/no-this-alias.mdx index af07e4353d3f..f5a9c86f0754 100644 --- a/packages/eslint-plugin/docs/rules/no-this-alias.mdx +++ b/packages/eslint-plugin/docs/rules/no-this-alias.mdx @@ -41,6 +41,8 @@ setTimeout(() => { ### `allowDestructuring` +{/* insert option description */} + It can sometimes be useful to destructure properties from a class instance, such as retrieving multiple properties from the instance in one of its methods. `allowDestructuring` allows those destructures and is `true` by default. You can explicitly disallow them by setting `allowDestructuring` to `false`. @@ -84,6 +86,8 @@ class ComponentLike { ### `allowedNames` +{/* insert option description */} + `no-this-alias` can alternately be used to allow only a specific list of names as `this` aliases. We recommend against this except as a transitory step towards fixing all rule violations. diff --git a/packages/eslint-plugin/docs/rules/no-type-alias.mdx b/packages/eslint-plugin/docs/rules/no-type-alias.mdx index 11068fbab2f6..3142deb7414f 100644 --- a/packages/eslint-plugin/docs/rules/no-type-alias.mdx +++ b/packages/eslint-plugin/docs/rules/no-type-alias.mdx @@ -114,7 +114,7 @@ and simplified types (primitives, tuples, unions, intersections, etc). ### `allowAliases` -This applies to primitive types and reference types. +{/* insert option description */} The setting accepts the following values: @@ -268,7 +268,7 @@ type Foo = Bar & Baz; ### `allowCallbacks` -This applies to function types. +{/* insert option description */} The setting accepts the following values: @@ -290,7 +290,7 @@ type Foo = (name: string, age: number) => string & Person; ### `allowConditionalTypes` -This applies to conditional types. +{/* insert option description */} Examples of **correct** code for the `{ "allowConditionalTypes": "always" }` option: @@ -300,7 +300,7 @@ type Foo = T extends number ? number : null; ### `allowConstructors` -This applies to constructor types. +{/* insert option description */} The setting accepts the following values: @@ -314,7 +314,7 @@ type Foo = new () => void; ### `allowLiterals` -This applies to literal types (`type Foo = { ... }`). +{/* insert option description */} The setting accepts the following options: @@ -421,7 +421,7 @@ type Foo = { name: string } & { age: number }; ### `allowMappedTypes` -This applies to literal types. +{/* insert option description */} The setting accepts the following values: @@ -524,7 +524,7 @@ type Foo = { [P in keyof T]?: T[P] } & { [P in keyof U]?: U[P] }; ### `allowTupleTypes` -This applies to tuple types (`type Foo = [number]`). +{/* insert option description */} The setting accepts the following options: @@ -599,7 +599,7 @@ type Foo = [string] | [number]; ### `allowGenerics` -This applies to generic types, including TypeScript provided global utility types (`type Foo = Record`). +{/* insert option description */} The setting accepts the following options: diff --git a/packages/eslint-plugin/docs/rules/no-unnecessary-boolean-literal-compare.mdx b/packages/eslint-plugin/docs/rules/no-unnecessary-boolean-literal-compare.mdx index 51c13eecb150..16462771e768 100644 --- a/packages/eslint-plugin/docs/rules/no-unnecessary-boolean-literal-compare.mdx +++ b/packages/eslint-plugin/docs/rules/no-unnecessary-boolean-literal-compare.mdx @@ -61,6 +61,8 @@ are **not** checked by default. ### `allowComparingNullableBooleansToTrue` +{/* insert option description */} + Examples of code for this rule with `{ allowComparingNullableBooleansToTrue: false }`: @@ -94,6 +96,8 @@ if (!someNullCondition) { ### `allowComparingNullableBooleansToFalse` +{/* insert option description */} + Examples of code for this rule with `{ allowComparingNullableBooleansToFalse: false }`: diff --git a/packages/eslint-plugin/docs/rules/no-unnecessary-condition.mdx b/packages/eslint-plugin/docs/rules/no-unnecessary-condition.mdx index befeea8b2401..06cfc9eb33fe 100644 --- a/packages/eslint-plugin/docs/rules/no-unnecessary-condition.mdx +++ b/packages/eslint-plugin/docs/rules/no-unnecessary-condition.mdx @@ -82,6 +82,8 @@ function bar(arg?: string | null) { ### `allowConstantLoopConditions` +{/* insert option description */} + Example of correct code for `{ allowConstantLoopConditions: true }`: ```ts option='{ "allowConstantLoopConditions": true }' showPlaygroundButton @@ -92,6 +94,8 @@ do {} while (true); ### `checkTypePredicates` +{/* insert option description */} + Example of additional incorrect code with `{ checkTypePredicates: true }`: ```ts option='{ "checkTypePredicates": true }' showPlaygroundButton @@ -132,6 +136,8 @@ However, in some contexts, it may be more appropriate to keep this option disabl ### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing` +{/* insert option description */} + :::danger Deprecated This option will be removed in the next major version of typescript-eslint. ::: diff --git a/packages/eslint-plugin/docs/rules/no-unnecessary-type-assertion.mdx b/packages/eslint-plugin/docs/rules/no-unnecessary-type-assertion.mdx index 4c34f32cae8f..497f843180e3 100644 --- a/packages/eslint-plugin/docs/rules/no-unnecessary-type-assertion.mdx +++ b/packages/eslint-plugin/docs/rules/no-unnecessary-type-assertion.mdx @@ -75,6 +75,8 @@ function foo(x: number | undefined): number { ### `typesToIgnore` +{/* insert option description */} + With `@typescript-eslint/no-unnecessary-type-assertion: ["error", { typesToIgnore: ['Foo'] }]`, the following is **correct** code: ```ts option='{ "typesToIgnore": ["Foo"] }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/no-use-before-define.mdx b/packages/eslint-plugin/docs/rules/no-use-before-define.mdx index 29bf8b75a0a7..5d57c1814bbe 100644 --- a/packages/eslint-plugin/docs/rules/no-use-before-define.mdx +++ b/packages/eslint-plugin/docs/rules/no-use-before-define.mdx @@ -33,7 +33,7 @@ const defaultOptions: Options = { ### `enums` -Whether to check references to enums before the enum declaration. +{/* insert option description */} If this is `true`, this rule warns every reference to a enum before the enum declaration. If this is `false`, this rule will ignore references to enums, when the reference is in a child scope. @@ -69,7 +69,7 @@ enum Foo { ### `typedefs` -Whether to check references to types before the type declaration. +{/* insert option description */} If this is `true`, this rule warns every reference to a type before the type declaration. If this is `false`, this rule will ignore references to types. @@ -83,7 +83,7 @@ type StringOrNumber = string | number; ### `ignoreTypeReferences` -Whether to ignore type references, such as in type annotations and assertions. +{/* insert option description */} If this is `true`, this rule ignores all type references. If this is `false`, this will check all type references. diff --git a/packages/eslint-plugin/docs/rules/no-var-requires.mdx b/packages/eslint-plugin/docs/rules/no-var-requires.mdx index c9945304a8a2..fc3e65631bbc 100644 --- a/packages/eslint-plugin/docs/rules/no-var-requires.mdx +++ b/packages/eslint-plugin/docs/rules/no-var-requires.mdx @@ -44,6 +44,8 @@ import foo from 'foo'; ### `allow` +{/* insert option description */} + A array of strings. These strings will be compiled into regular expressions with the `u` flag and be used to test against the imported path. A common use case is to allow importing `package.json`. This is because `package.json` commonly lives outside of the TS root directory, so statically importing it would lead to root directory conflicts, especially with `resolveJsonModule` enabled. You can also use it to allow importing any JSON if your environment doesn't support JSON modules, or use it for other cases where `import` statements cannot work. With `{allow: ['/package\\.json$']}`: diff --git a/packages/eslint-plugin/docs/rules/parameter-properties.mdx b/packages/eslint-plugin/docs/rules/parameter-properties.mdx index b9915dd65e68..1e60721f419f 100644 --- a/packages/eslint-plugin/docs/rules/parameter-properties.mdx +++ b/packages/eslint-plugin/docs/rules/parameter-properties.mdx @@ -24,6 +24,8 @@ It may take an options object containing either or both of: ### `allow` +{/* insert option description */} + If you would like to ignore certain kinds of properties then you may pass an object containing `"allow"` as an array of any of the following options: - `allow`, an array containing one or more of the allowed modifiers. Valid values are: @@ -50,8 +52,10 @@ For example, to ignore `public` properties: ### `prefer` -By default, the rule prefers class property (`"class-property"`). -You can switch it to instead preferring parameter property with (`"parameter-property"`). +{/* insert option description */} + +By default, the rule prefers class properties. +You can switch it to instead preferring parameter properties with (`"parameter-property"`). In `"parameter-property"` mode, the rule will issue a report when: diff --git a/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx b/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx index 411e376b7243..d4aa0980e6b4 100644 --- a/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-destructuring.mdx @@ -80,7 +80,7 @@ const defaultOptions: Options = [ ### `enforceForDeclarationWithTypeAnnotation` -When set to `true`, type annotated variable declarations are enforced to use destructuring assignment. +{/* insert option description */} Examples with `{ enforceForDeclarationWithTypeAnnotation: true }`: diff --git a/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx b/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx index 31834a871a2b..9d2e2ffb81a3 100644 --- a/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-literal-enum-member.mdx @@ -68,7 +68,7 @@ enum Valid { ### `allowBitwiseExpressions` -Whether to allow using bitwise expressions in enum initializers (default: `false`). +{/* insert option description */} Examples of code for the `{ "allowBitwiseExpressions": true }` option: diff --git a/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx b/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx index f7fc10e05e14..73822ae7198d 100644 --- a/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-nullish-coalescing.mdx @@ -25,7 +25,7 @@ This rule will not work as expected if [`strictNullChecks`](https://www.typescri ### `ignoreTernaryTests` -Whether to ignore any ternary expressions that could be simplified by using the nullish coalescing operator. This is set to `false` by default. +{/* insert option description */} Incorrect code for `ignoreTernaryTests: false`, and correct code for `ignoreTernaryTests: true`: @@ -65,7 +65,7 @@ foo ?? 'a string'; ### `ignoreConditionalTests` -Whether to ignore cases that are located within a conditional test. This is set to `true` by default. +{/* insert option description */} Generally expressions within conditional tests intentionally use the falsy fallthrough behavior of the logical or operator, meaning that fixing the operator to the nullish coalesce operator could cause bugs. @@ -107,7 +107,7 @@ a ?? b ? true : false; ### `ignoreMixedLogicalExpressions` -Whether to ignore any logical or expressions that are part of a mixed logical expression (with `&&`). This is set to `false` by default. +{/* insert option description */} Generally expressions within mixed logical expressions intentionally use the falsy fallthrough behavior of the logical or operator, meaning that fixing the operator to the nullish coalesce operator could cause bugs. @@ -147,7 +147,7 @@ a ?? (b && c && d); ### `ignorePrimitives` -Whether to ignore all (`true`) or some (an object with properties) primitive types. +{/* insert option description */} If you would like to ignore expressions containing operands of certain primitive types that can be falsy then you may pass an object containing a boolean value for each primitive: @@ -174,6 +174,8 @@ Also, if you would like to ignore all primitives types, you can set `ignorePrimi ### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing` +{/* insert option description */} + :::danger Deprecated > This option will be removed in the next major version of typescript-eslint. diff --git a/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx b/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx index ee7aa6abf42f..f1627d853cab 100644 --- a/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-optional-chain.mdx @@ -68,6 +68,8 @@ Specifically the argument of the not operator (`!loose`) or a bare value in a lo ### `allowPotentiallyUnsafeFixesThatModifyTheReturnTypeIKnowWhatImDoing` +{/* insert option description */} + When this option is `true`, the rule will provide an auto-fixer for cases where the return type of the expression would change. For example for the expression `!foo || foo.bar` the return type of the expression is `true | T`, however for the equivalent optional chain `foo?.bar` the return type of the expression is `undefined | T`. Thus changing the code from a logical expression to an optional chain expression has altered the type of the expression. In some cases this distinction _may_ matter - which is why these fixers are considered unsafe - they may break the build! For example in the following code: @@ -89,11 +91,12 @@ When this option is `false` unsafe cases will have suggestion fixers provided in ### `checkAny` -When this option is `true` the rule will check operands that are typed as `any` when inspecting "loose boolean" operands. +{/* insert option description */} - +Examples of code for this rule with `{ checkAny: false }`: - + + ```ts option='{ "checkAny": true }' declare const thing: any; @@ -102,7 +105,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkAny": false }' declare const thing: any; @@ -115,11 +118,12 @@ thing && thing.toString(); ### `checkUnknown` -When this option is `true` the rule will check operands that are typed as `unknown` when inspecting "loose boolean" operands. +{/* insert option description */} - +Examples of code for this rule with `{ checkUnknown: false }`: - + + ```ts option='{ "checkUnknown": true }' declare const thing: unknown; @@ -128,7 +132,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkUnknown": false }' declare const thing: unknown; @@ -141,11 +145,12 @@ thing && thing.toString(); ### `checkString` -When this option is `true` the rule will check operands that are typed as `string` when inspecting "loose boolean" operands. +{/* insert option description */} - +Examples of code for this rule with `{ checkString: false }`: - + + ```ts option='{ "checkString": true }' declare const thing: string; @@ -154,7 +159,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkString": false }' declare const thing: string; @@ -167,11 +172,12 @@ thing && thing.toString(); ### `checkNumber` -When this option is `true` the rule will check operands that are typed as `number` when inspecting "loose boolean" operands. +{/* insert option description */} - +Examples of code for this rule with `{ checkNumber: false }`: - + + ```ts option='{ "checkNumber": true }' declare const thing: number; @@ -180,7 +186,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkNumber": false }' declare const thing: number; @@ -193,7 +199,7 @@ thing && thing.toString(); ### `checkBoolean` -When this option is `true` the rule will check operands that are typed as `boolean` when inspecting "loose boolean" operands. +{/* insert option description */} :::note @@ -209,9 +215,10 @@ The boolean expression narrows out the non-nullish falsy cases - so converting t ::: - +Examples of code for this rule with `{ checkBoolean: false }`: - + + ```ts option='{ "checkBoolean": true }' declare const thing: true; @@ -220,7 +227,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkBoolean": false }' declare const thing: true; @@ -233,11 +240,12 @@ thing && thing.toString(); ### `checkBigInt` -When this option is `true` the rule will check operands that are typed as `bigint` when inspecting "loose boolean" operands. +{/* insert option description */} - +Examples of code for this rule with `{ checkBigInt: false }`: - + + ```ts option='{ "checkBigInt": true }' declare const thing: bigint; @@ -246,7 +254,7 @@ thing && thing.toString(); ``` - + ```ts option='{ "checkBigInt": false }' declare const thing: bigint; @@ -259,11 +267,12 @@ thing && thing.toString(); ### `requireNullish` -When this option is `true` the rule will skip operands that are not typed with `null` and/or `undefined` when inspecting "loose boolean" operands. +{/* insert option description */} - +Examples of code for this rule with `{ requireNullish: false }`: - + + ```ts option='{ "requireNullish": true }' declare const thing1: string | null; @@ -271,7 +280,7 @@ thing1 && thing1.toString(); ``` - + ```ts option='{ "requireNullish": true }' declare const thing1: string | null; diff --git a/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx b/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx index f89d653bd63e..02b7dc9776b7 100644 --- a/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-readonly-parameter-types.mdx @@ -140,7 +140,8 @@ interface Foo { ### `allow` -An array of type specifiers to ignore. +{/* insert option description */} + Some complex types cannot easily be made readonly, for example the `HTMLElement` type or the `JQueryStatic` type from `@types/jquery`. This option allows you to globally disable reporting of such types. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). @@ -251,7 +252,8 @@ function fn(arg: Foo) {} ### `checkParameterProperties` -Whether to check class parameter properties. +{/* insert option description */} + Because parameter properties create properties on the class, it may be undesirable to force them to be readonly. Examples of code for this rule with `{checkParameterProperties: true}`: @@ -290,7 +292,8 @@ class Foo { ### `ignoreInferredTypes` -Whether to ignore parameters which don't explicitly specify a type. +{/* insert option description */} + This may be desirable in cases where an external dependency specifies a callback with mutable parameters, and manually annotating the callback's parameters is undesirable. Examples of code for this rule with `{ignoreInferredTypes: true}`: @@ -348,7 +351,8 @@ export const acceptsCallback: AcceptsCallback; ### `treatMethodsAsReadonly` -Whether to treat all mutable methods as though they are readonly. +{/* insert option description */} + This may be desirable when you are never reassigning methods. Examples of code for this rule with `{treatMethodsAsReadonly: false}`: diff --git a/packages/eslint-plugin/docs/rules/prefer-readonly.mdx b/packages/eslint-plugin/docs/rules/prefer-readonly.mdx index a3fe49e0336c..c711102038d6 100644 --- a/packages/eslint-plugin/docs/rules/prefer-readonly.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-readonly.mdx @@ -70,7 +70,7 @@ class Container { ### `onlyInlineLambdas` -You may pass `"onlyInlineLambdas": true` as a rule option within an object to restrict checking only to members immediately assigned a lambda value. +{/* insert option description */} ```jsonc { diff --git a/packages/eslint-plugin/docs/rules/prefer-string-starts-ends-with.mdx b/packages/eslint-plugin/docs/rules/prefer-string-starts-ends-with.mdx index cae79c26679b..cc0860bb7c7b 100644 --- a/packages/eslint-plugin/docs/rules/prefer-string-starts-ends-with.mdx +++ b/packages/eslint-plugin/docs/rules/prefer-string-starts-ends-with.mdx @@ -62,6 +62,8 @@ foo.endsWith('bar'); ### `allowSingleElementEquality` +{/* insert option description */} + If switched to `'always'`, the rule will allow equality checks against the first or last character in a string. This can be preferable in projects that don't deal with special character encodings and prefer a more succinct style. diff --git a/packages/eslint-plugin/docs/rules/promise-function-async.mdx b/packages/eslint-plugin/docs/rules/promise-function-async.mdx index aabe921925d3..f13da18e82ee 100644 --- a/packages/eslint-plugin/docs/rules/promise-function-async.mdx +++ b/packages/eslint-plugin/docs/rules/promise-function-async.mdx @@ -68,7 +68,8 @@ async function functionReturnsUnionWithPromiseImplicitly(p: boolean) { ### `allowAny` -Whether to ignore functions that return `any` or `unknown`. +{/* insert option description */} + If you want additional safety, consider turning this option off, as it makes the rule less able to catch incorrect Promise behaviors. Examples of code with `{ "allowAny": false }`: @@ -92,6 +93,8 @@ const returnsAny = async () => ({}) as any; ### `allowedPromiseNames` +{/* insert option description */} + For projects that use constructs other than the global built-in `Promise` for asynchronous code. This option allows specifying string names of classes or interfaces that cause a function to be checked as well. @@ -120,23 +123,19 @@ const returnsBluebird = async () => new Bluebird(() => {}); ### `checkArrowFunctions` -Whether to check arrow functions. -`true` by default, but can be set to `false` to ignore them. +{/* insert option description */} ### `checkFunctionDeclarations` -Whether to check standalone function declarations. -`true` by default, but can be set to `false` to ignore them. +{/* insert option description */} ### `checkFunctionExpressions` -Whether to check inline function expressions. -`true` by default, but can be set to `false` to ignore them. +{/* insert option description */} ### `checkMethodDeclarations` -Whether to check methods on classes and object literals. -`true` by default, but can be set to `false` to ignore them. +{/* insert option description */} ## When Not To Use It diff --git a/packages/eslint-plugin/docs/rules/require-array-sort-compare.mdx b/packages/eslint-plugin/docs/rules/require-array-sort-compare.mdx index 5c23955cc823..7ca4b942dcf3 100644 --- a/packages/eslint-plugin/docs/rules/require-array-sort-compare.mdx +++ b/packages/eslint-plugin/docs/rules/require-array-sort-compare.mdx @@ -57,6 +57,8 @@ userDefinedType.sort(); ### `ignoreStringArrays` +{/* insert option description */} + Examples of code for this rule with `{ ignoreStringArrays: true }`: diff --git a/packages/eslint-plugin/docs/rules/restrict-plus-operands.mdx b/packages/eslint-plugin/docs/rules/restrict-plus-operands.mdx index c96c8aa12ede..4a7159aaac7a 100644 --- a/packages/eslint-plugin/docs/rules/restrict-plus-operands.mdx +++ b/packages/eslint-plugin/docs/rules/restrict-plus-operands.mdx @@ -74,6 +74,8 @@ Safer alternatives to using the `allow*` options include: ### `allowAny` +{/* insert option description */} + Examples of code for this rule with `{ allowAny: true }`: @@ -97,6 +99,8 @@ let fn = (a: string, b: any) => a + b; ### `allowBoolean` +{/* insert option description */} + Examples of code for this rule with `{ allowBoolean: true }`: @@ -120,6 +124,8 @@ let fn = (a: string, b: boolean) => a + b; ### `allowNullish` +{/* insert option description */} + Examples of code for this rule with `{ allowNullish: true }`: @@ -147,6 +153,8 @@ let fn = (a: string, b: null) => a + b; ### `allowNumberAndString` +{/* insert option description */} + Examples of code for this rule with `{ allowNumberAndString: true }`: @@ -170,6 +178,8 @@ let fn = (a: number, b: number | string) => a + b; ### `allowRegExp` +{/* insert option description */} + Examples of code for this rule with `{ allowRegExp: true }`: @@ -191,6 +201,8 @@ let fn = (a: string, b: RegExp) => a + b; ### `skipCompoundAssignments` +{/* insert option description */} + Examples of code for this rule with `{ skipCompoundAssignments: false }`: diff --git a/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx b/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx index 60ea75a7c65e..9ea40aa8c11f 100644 --- a/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx +++ b/packages/eslint-plugin/docs/rules/restrict-template-expressions.mdx @@ -55,7 +55,7 @@ const msg3 = `stringWithKindProp = ${stringWithKindProp}`; ### `allowNumber` -Whether to allow `number` typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowNumber: true }`: @@ -73,7 +73,7 @@ Consider using [`.toFixed()`](https://developer.mozilla.org/en-US/docs/Web/JavaS ### `allowBoolean` -Whether to allow Boolean typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowBoolean: true }`: @@ -85,7 +85,7 @@ const msg2 = `arg = ${arg || 'not truthy'}`; ### `allowAny` -Whether to allow `any` typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowAny: true }`: @@ -97,7 +97,7 @@ const msg2 = `arg = ${user.name || 'the user with no name'}`; ### `allowNullish` -Whether to allow `null` or `undefined` typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowNullish: true }`: @@ -108,7 +108,7 @@ const msg1 = `arg = ${arg}`; ### `allowRegExp` -Whether to allow `RegExp` typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowRegExp: true }`: @@ -124,7 +124,7 @@ const msg1 = `arg = ${arg}`; ### `allowNever` -Whether to allow `never` typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowNever: true }`: @@ -135,7 +135,7 @@ const msg1 = typeof arg === 'string' ? arg : `arg = ${arg}`; ### `allowArray` -Whether to allow `Array` typed values in template expressions. +{/* insert option description */} Examples of additional **correct** code for this rule with `{ allowArray: true }`: @@ -146,6 +146,8 @@ const msg1 = `arg = ${arg}`; ### `allow` +{/* insert option description */} + Whether to allow additional types in template expressions. This option takes the shared [`TypeOrValueSpecifier` format](/packages/type-utils/type-or-value-specifier). diff --git a/packages/eslint-plugin/docs/rules/return-await.mdx b/packages/eslint-plugin/docs/rules/return-await.mdx index 9be63cc9600c..34173fae9265 100644 --- a/packages/eslint-plugin/docs/rules/return-await.mdx +++ b/packages/eslint-plugin/docs/rules/return-await.mdx @@ -189,6 +189,8 @@ async function validInTryCatch7() { ### `always` +{/* insert option description */} + Requires that all returned promises be awaited. This is a good option if you like the consistency of simply always awaiting promises, or prefer not having to consider the distinction between error-handling contexts and ordinary contexts. @@ -268,6 +270,8 @@ async function asyncFunction(): Promise { ### `never` +{/* insert option description */} + Disallows awaiting any returned promises. :::warning diff --git a/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx b/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx index 9ce8157deffb..8ed863fb1594 100644 --- a/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx +++ b/packages/eslint-plugin/docs/rules/sort-type-constituents.mdx @@ -96,7 +96,7 @@ type T4 = ### `caseSensitive` -Whether to sort using case sensitive string comparisons. +{/* insert option description */} Examples of code with `{ "caseSensitive": true }`: @@ -119,7 +119,7 @@ type T = 'DeleteForever' | 'DeletedAt'; ### `checkIntersections` -Whether to check intersection types (`&`). +{/* insert option description */} Examples of code with `{ "checkIntersections": true }` (the default): @@ -142,7 +142,7 @@ type ExampleIntersection = A & B; ### `checkUnions` -Whether to check union types (`|`). +{/* insert option description */} Examples of code with `{ "checkUnions": true }` (the default): @@ -165,6 +165,8 @@ type ExampleUnion = A | B; ### `groupOrder` +{/* insert option description */} + Each constituent of the type is placed into a group, and then the rule sorts alphabetically within each group. The ordering of groups is determined by this option. diff --git a/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx b/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx index 820d4d188d4e..a48b3a37247d 100644 --- a/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx +++ b/packages/eslint-plugin/docs/rules/strict-boolean-expressions.mdx @@ -95,55 +95,65 @@ const foo = (arg: any) => (Boolean(arg) ? 1 : 0); ### `allowString` -Allows `string` in a boolean context. -This is safe because strings have only one falsy value (`""`). +{/* insert option description */} + +This can be safe because strings have only one falsy value (`""`). Set this to `false` if you prefer the explicit `str != ""` or `str.length > 0` style. ### `allowNumber` -Allows `number` in a boolean context. -This is safe because numbers have only two falsy values (`0` and `NaN`). +{/* insert option description */} + +This can be safe because numbers have only two falsy values (`0` and `NaN`). Set this to `false` if you prefer the explicit `num != 0` and `!Number.isNaN(num)` style. ### `allowNullableObject` -Allows `object | function | symbol | null | undefined` in a boolean context. -This is safe because objects, functions and symbols don't have falsy values. +{/* insert option description */} + +This can be safe because objects, functions, and symbols don't have falsy values. Set this to `false` if you prefer the explicit `obj != null` style. ### `allowNullableBoolean` -Allows `boolean | null | undefined` in a boolean context. +{/* insert option description */} + This is unsafe because nullable booleans can be either `false` or nullish. Set this to `false` if you want to enforce explicit `bool ?? false` or `bool ?? true` style. Set this to `true` if you don't mind implicitly treating false the same as a nullish value. ### `allowNullableString` -Allows `string | null | undefined` in a boolean context. +{/* insert option description */} + This is unsafe because nullable strings can be either an empty string or nullish. Set this to `true` if you don't mind implicitly treating an empty string the same as a nullish value. ### `allowNullableNumber` -Allows `number | null | undefined` in a boolean context. +{/* insert option description */} + This is unsafe because nullable numbers can be either a falsy number or nullish. Set this to `true` if you don't mind implicitly treating zero or NaN the same as a nullish value. ### `allowNullableEnum` -Allows `enum | null | undefined` in a boolean context. +{/* insert option description */} + This is unsafe because nullable enums can be either a falsy number or nullish. Set this to `true` if you don't mind implicitly treating an enum whose value is zero the same as a nullish value. ### `allowAny` -Allows `any` in a boolean context. -This is unsafe for obvious reasons. +{/* insert option description */} + +This is unsafe for because `any` allows any values and disables many type checking checks. Set this to `true` at your own risk. ### `allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing` +{/* insert option description */} + :::danger Deprecated This option will be removed in the next major version of typescript-eslint. diff --git a/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx b/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx index f629d8ee53ac..538b911049c3 100644 --- a/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx +++ b/packages/eslint-plugin/docs/rules/switch-exhaustiveness-check.mdx @@ -18,7 +18,9 @@ This rule reports when a `switch` statement over a value typed as a union of lit ### `allowDefaultCaseForExhaustiveSwitch` -Defaults to true. If set to false, this rule will also report when a `switch` statement has a case for everything in a union and _also_ contains a `default` case. Thus, by setting this option to false, the rule becomes stricter. +{/* insert option description */} + +If set to false, this rule will also report when a `switch` statement has a case for everything in a union and _also_ contains a `default` case. Thus, by setting this option to false, the rule becomes stricter. When a `switch` statement over a union type is exhaustive, a final `default` case would be a form of dead code. Additionally, if a new value is added to the union type, a `default` would prevent the `switch-exhaustiveness-check` rule from reporting on the new case not being handled in the `switch` statement. @@ -34,7 +36,9 @@ If your project has many intentionally redundant `default` cases, you may want t ### `requireDefaultForNonUnion` -Defaults to false. If set to true, this rule will also report when a `switch` statement switches over a non-union type (like a `number` or `string`, for example) and that `switch` statement does not have a `default` case. Thus, by setting this option to true, the rule becomes stricter. +{/* insert option description */} + +If set to true, this rule will also report when a `switch` statement switches over a non-union type (like a `number` or `string`, for example) and that `switch` statement does not have a `default` case. Thus, by setting this option to true, the rule becomes stricter. This is generally desirable so that `number` and `string` switches will be subject to the same exhaustive checks that your other switches are. diff --git a/packages/eslint-plugin/docs/rules/triple-slash-reference.mdx b/packages/eslint-plugin/docs/rules/triple-slash-reference.mdx index 43a043671f55..2fe7847f34c3 100644 --- a/packages/eslint-plugin/docs/rules/triple-slash-reference.mdx +++ b/packages/eslint-plugin/docs/rules/triple-slash-reference.mdx @@ -20,6 +20,8 @@ Specifying `'always'` disables this lint rule for that kind of reference. ### `lib` +{/* insert option description */} + When set to `'never'`, bans `/// ` and enforces using an `import` instead: @@ -43,6 +45,8 @@ import { value } from 'code'; ### `path` +{/* insert option description */} + When set to `'never'`, bans `/// ` and enforces using an `import` instead: @@ -66,6 +70,8 @@ import { value } from 'code'; ### `types` +{/* insert option description */} + When set to `'never'`, bans `/// ` and enforces using an `import` instead: diff --git a/packages/eslint-plugin/docs/rules/typedef.mdx b/packages/eslint-plugin/docs/rules/typedef.mdx index 46fa0134c90f..8af5c045244a 100644 --- a/packages/eslint-plugin/docs/rules/typedef.mdx +++ b/packages/eslint-plugin/docs/rules/typedef.mdx @@ -62,7 +62,7 @@ For example, with the following configuration: ### `arrayDestructuring` -Whether to enforce type annotations on variables declared using array destructuring. +{/* insert option description */} Examples of code with `{ "arrayDestructuring": true }`: @@ -91,7 +91,7 @@ for (const [key, val] of new Map([['key', 1]])) { ### `arrowParameter` -Whether to enforce type annotations for parameters of arrow functions. +{/* insert option description */} Examples of code with `{ "arrowParameter": true }`: @@ -126,7 +126,7 @@ const mapper = { ### `memberVariableDeclaration` -Whether to enforce type annotations on member variables of classes. +{/* insert option description */} Examples of code with `{ "memberVariableDeclaration": true }`: @@ -155,7 +155,7 @@ class ContainsText { ### `objectDestructuring` -Whether to enforce type annotations on variables declared using object destructuring. +{/* insert option description */} Examples of code with `{ "objectDestructuring": true }`: @@ -183,7 +183,7 @@ for (const { key, val } of [{ key: 'key', val: 1 }]) { ### `parameter` -Whether to enforce type annotations for parameters of functions and methods. +{/* insert option description */} Examples of code with `{ "parameter": true }`: @@ -250,7 +250,7 @@ class Logger { ### `propertyDeclaration` -Whether to enforce type annotations for properties of interfaces and types. +{/* insert option description */} Examples of code with `{ "propertyDeclaration": true }`: @@ -279,7 +279,7 @@ type Members = { ### `variableDeclaration` -Whether to enforce type annotations for variable declarations, excluding array and object destructuring. +{/* insert option description */} Examples of code with `{ "variableDeclaration": true }`: @@ -306,7 +306,7 @@ let delayedText: string; ### `variableDeclarationIgnoreFunction` -Whether to ignore variable declarations for non-arrow and arrow functions. +{/* insert option description */} Examples of code with `{ "variableDeclaration": true, "variableDeclarationIgnoreFunction": true }`: diff --git a/packages/eslint-plugin/docs/rules/unbound-method.mdx b/packages/eslint-plugin/docs/rules/unbound-method.mdx index 7dd2d5aa7ecd..bf48bea5d65f 100644 --- a/packages/eslint-plugin/docs/rules/unbound-method.mdx +++ b/packages/eslint-plugin/docs/rules/unbound-method.mdx @@ -87,6 +87,8 @@ const { double } = arith; ### `ignoreStatic` +{/* insert option description */} + Examples of **correct** code for this rule with `{ ignoreStatic: true }`: ```ts option='{ "ignoreStatic": true }' showPlaygroundButton diff --git a/packages/eslint-plugin/docs/rules/unified-signatures.mdx b/packages/eslint-plugin/docs/rules/unified-signatures.mdx index 6e2fd8d5f804..6813957a5e80 100644 --- a/packages/eslint-plugin/docs/rules/unified-signatures.mdx +++ b/packages/eslint-plugin/docs/rules/unified-signatures.mdx @@ -55,6 +55,8 @@ function f(...a: string[]): void; ### `ignoreDifferentlyNamedParameters` +{/* insert option description */} + Examples of code for this rule with `ignoreDifferentlyNamedParameters`: diff --git a/packages/eslint-plugin/src/rules/class-literal-property-style.ts b/packages/eslint-plugin/src/rules/class-literal-property-style.ts index dd1132f3b34d..f59c061f3767 100644 --- a/packages/eslint-plugin/src/rules/class-literal-property-style.ts +++ b/packages/eslint-plugin/src/rules/class-literal-property-style.ts @@ -73,6 +73,7 @@ export default createRule({ schema: [ { type: 'string', + description: 'Which literal class member syntax to prefer.', enum: ['fields', 'getters'], }, ], diff --git a/packages/eslint-plugin/src/rules/class-methods-use-this.ts b/packages/eslint-plugin/src/rules/class-methods-use-this.ts index 1d3beff94d25..f049781f7d61 100644 --- a/packages/eslint-plugin/src/rules/class-methods-use-this.ts +++ b/packages/eslint-plugin/src/rules/class-methods-use-this.ts @@ -40,19 +40,19 @@ export default createRule({ type: 'boolean', default: true, description: - 'Enforces that functions used as instance field initializers utilize `this`', + 'Enforces that functions used as instance field initializers utilize `this`.', }, exceptMethods: { type: 'array', description: - 'Allows specified method names to be ignored with this rule', + 'Allows specified method names to be ignored with this rule.', items: { type: 'string', }, }, ignoreClassesThatImplementAnInterface: { description: - 'Ignore classes that specifically implement some interface', + 'Makes the rule ignore class members that are defined within a class that `implements` a type', oneOf: [ { type: 'boolean', diff --git a/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts b/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts index f3033536b653..9c92cd98188c 100644 --- a/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts +++ b/packages/eslint-plugin/src/rules/consistent-generic-constructors.ts @@ -26,6 +26,7 @@ export default createRule({ schema: [ { type: 'string', + description: 'Which constructor call syntax to prefer.', enum: ['type-annotation', 'constructor'], }, ], diff --git a/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts b/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts index 1908d274f0ff..ad17704bf1fb 100644 --- a/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts +++ b/packages/eslint-plugin/src/rules/consistent-indexed-object-style.ts @@ -23,6 +23,7 @@ export default createRule({ schema: [ { type: 'string', + description: 'Which indexed object syntax to prefer.', enum: ['record', 'index-signature'], }, ], diff --git a/packages/eslint-plugin/src/rules/consistent-type-definitions.ts b/packages/eslint-plugin/src/rules/consistent-type-definitions.ts index 2505b7c54262..9c57c4f40327 100644 --- a/packages/eslint-plugin/src/rules/consistent-type-definitions.ts +++ b/packages/eslint-plugin/src/rules/consistent-type-definitions.ts @@ -21,6 +21,7 @@ export default createRule({ schema: [ { type: 'string', + description: 'Which type definition syntax to prefer.', enum: ['interface', 'type'], }, ], diff --git a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts index b03a75cc210e..7dff44c330f9 100644 --- a/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts +++ b/packages/eslint-plugin/src/rules/explicit-member-accessibility.ts @@ -82,7 +82,11 @@ export default createRule({ }, additionalProperties: false, properties: { - accessibility: { $ref: '#/items/0/$defs/accessibilityLevel' }, + accessibility: { + $ref: '#/items/0/$defs/accessibilityLevel', + description: + 'Which accessibility modifier is required to exist or not exist.', + }, ignoredMethodNames: { type: 'array', description: 'Specific method names that may be ignored.', @@ -93,6 +97,8 @@ export default createRule({ overrides: { type: 'object', additionalProperties: false, + description: + 'Changes to required accessibility modifiers for specific kinds of class members.', properties: { accessors: { $ref: '#/items/0/$defs/accessibilityLevel' }, constructors: { $ref: '#/items/0/$defs/accessibilityLevel' }, diff --git a/packages/eslint-plugin/src/rules/no-invalid-void-type.ts b/packages/eslint-plugin/src/rules/no-invalid-void-type.ts index 34f3f8cb22a1..af8ef4d79df7 100644 --- a/packages/eslint-plugin/src/rules/no-invalid-void-type.ts +++ b/packages/eslint-plugin/src/rules/no-invalid-void-type.ts @@ -52,9 +52,15 @@ export default createRule<[Options], MessageIds>({ description: 'Whether `void` can be used as a valid value for generic type parameters.', oneOf: [ - { type: 'boolean' }, + { + type: 'boolean', + description: + 'Whether `void` can be used as a valid value for all generic type parameters.', + }, { type: 'array', + description: + 'Allowlist of types that may accept `void` as a generic type parameter.', items: { type: 'string' }, minItems: 1, }, @@ -89,7 +95,7 @@ export default createRule<[Options], MessageIds>({ /** * @brief check if the given void keyword is used as a valid generic type * - * reports if the type parametrized by void is not in the whitelist, or + * reports if the type parametrized by void is not in the allowlist, or * allowInGenericTypeArguments is false. * no-op if the given void keyword is not used as generic type */ @@ -104,7 +110,7 @@ export default createRule<[Options], MessageIds>({ return; } - // check whitelist + // check allowlist if (Array.isArray(allowInGenericTypeArguments)) { const fullyQualifiedName = context.sourceCode .getText(node.parent.parent.typeName) diff --git a/packages/eslint-plugin/src/rules/no-misused-promises.ts b/packages/eslint-plugin/src/rules/no-misused-promises.ts index ac8c359fc1cc..6498b10d0f52 100644 --- a/packages/eslint-plugin/src/rules/no-misused-promises.ts +++ b/packages/eslint-plugin/src/rules/no-misused-promises.ts @@ -105,17 +105,27 @@ export default createRule({ properties: { checksConditionals: { type: 'boolean', + description: + 'Whether to warn when a Promise is provided to conditional statements.', }, checksSpreads: { type: 'boolean', description: 'Whether to warn when `...` spreading a `Promise`.', }, checksVoidReturn: { + description: + 'Whether to warn when a Promise is returned from a function typed as returning `void`.', oneOf: [ - { type: 'boolean' }, + { + type: 'boolean', + description: + 'Whether to disable checking all asynchronous functions.', + }, { type: 'object', additionalProperties: false, + description: + 'Which forms of functions may have checking disabled.', properties: { arguments: { type: 'boolean', diff --git a/packages/eslint-plugin/src/rules/no-restricted-imports.ts b/packages/eslint-plugin/src/rules/no-restricted-imports.ts index d407a5f66df5..78ad01f3f864 100644 --- a/packages/eslint-plugin/src/rules/no-restricted-imports.ts +++ b/packages/eslint-plugin/src/rules/no-restricted-imports.ts @@ -83,7 +83,7 @@ const baseSchema = baseRule.meta.schema as { const allowTypeImportsOptionSchema: JSONSchema4ObjectSchema['properties'] = { allowTypeImports: { type: 'boolean', - description: 'Disallow value imports, but allow type-only imports.', + description: 'Whether to allow type-only imports for a path.', }, }; diff --git a/packages/eslint-plugin/src/rules/no-restricted-types.ts b/packages/eslint-plugin/src/rules/no-restricted-types.ts index 8192b9380c7e..a6f22308919b 100644 --- a/packages/eslint-plugin/src/rules/no-restricted-types.ts +++ b/packages/eslint-plugin/src/rules/no-restricted-types.ts @@ -89,17 +89,17 @@ export default createRule({ oneOf: [ { type: 'boolean', - description: 'Bans the type with the default message', + description: 'Bans the type with the default message.', enum: [true], }, { type: 'string', - description: 'Bans the type with a custom message', + description: 'Bans the type with a custom message.', }, { type: 'object', additionalProperties: false, - description: 'Bans a type', + description: 'Bans a type.', properties: { fixWith: { type: 'string', @@ -108,7 +108,7 @@ export default createRule({ }, message: { type: 'string', - description: 'Custom error message', + description: 'Custom error message.', }, suggest: { type: 'array', @@ -127,6 +127,8 @@ export default createRule({ additionalProperties: { $ref: '#/items/0/$defs/banConfig', }, + description: + 'An object whose keys are the types you want to ban, and the values are error messages.', }, }, }, diff --git a/packages/eslint-plugin/src/rules/no-use-before-define.ts b/packages/eslint-plugin/src/rules/no-use-before-define.ts index 8350f6477318..e89868efd695 100644 --- a/packages/eslint-plugin/src/rules/no-use-before-define.ts +++ b/packages/eslint-plugin/src/rules/no-use-before-define.ts @@ -237,7 +237,10 @@ export default createRule({ type: 'object', additionalProperties: false, properties: { - allowNamedExports: { type: 'boolean' }, + allowNamedExports: { + type: 'boolean', + description: 'Whether to ignore named exports.', + }, classes: { type: 'boolean', description: diff --git a/packages/eslint-plugin/src/rules/prefer-destructuring.ts b/packages/eslint-plugin/src/rules/prefer-destructuring.ts index fdf3bc1deeaf..1ad1a749492a 100644 --- a/packages/eslint-plugin/src/rules/prefer-destructuring.ts +++ b/packages/eslint-plugin/src/rules/prefer-destructuring.ts @@ -55,9 +55,13 @@ const schema: readonly JSONSchema4[] = [ properties: { enforceForDeclarationWithTypeAnnotation: { type: 'boolean', + description: + 'Whether to enforce destructuring on variable declarations with type annotations.', }, enforceForRenamedProperties: { type: 'boolean', + description: + 'Whether to enforce destructuring that use a different variable name than the property name.', }, }, }, diff --git a/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts b/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts index 94424989b955..56e77925b489 100644 --- a/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts +++ b/packages/eslint-plugin/src/rules/prefer-nullish-coalescing.ts @@ -87,15 +87,29 @@ export default createRule({ oneOf: [ { type: 'object', + description: 'Which primitives types may be ignored.', properties: { - bigint: { type: 'boolean' }, - boolean: { type: 'boolean' }, - number: { type: 'boolean' }, - string: { type: 'boolean' }, + bigint: { + type: 'boolean', + description: 'Ignore bigint primitive types.', + }, + boolean: { + type: 'boolean', + description: 'Ignore boolean primitive types.', + }, + number: { + type: 'boolean', + description: 'Ignore number primitive types.', + }, + string: { + type: 'boolean', + description: 'Ignore string primitive types.', + }, }, }, { type: 'boolean', + description: 'Ignore all primitive types.', enum: [true], }, ], diff --git a/packages/eslint-plugin/src/rules/sort-type-constituents.ts b/packages/eslint-plugin/src/rules/sort-type-constituents.ts index d6a2779ba8f4..33b65a12ff7d 100644 --- a/packages/eslint-plugin/src/rules/sort-type-constituents.ts +++ b/packages/eslint-plugin/src/rules/sort-type-constituents.ts @@ -142,15 +142,16 @@ export default createRule({ properties: { caseSensitive: { type: 'boolean', - description: 'Whether to sort using case sensitive sorting.', + description: + 'Whether to sort using case sensitive string comparisons.', }, checkIntersections: { type: 'boolean', - description: 'Whether to check intersection types.', + description: 'Whether to check intersection types (`&`).', }, checkUnions: { type: 'boolean', - description: 'Whether to check union types.', + description: 'Whether to check union types (`|`).', }, groupOrder: { type: 'array', diff --git a/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts b/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts index 1933d2899c14..eb127d434d78 100644 --- a/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts +++ b/packages/eslint-plugin/src/rules/strict-boolean-expressions.ts @@ -132,7 +132,7 @@ export default createRule({ properties: { allowAny: { type: 'boolean', - description: 'Whether to allow `any` in a boolean context.', + description: 'Whether to allow `any`s in a boolean context.', }, allowNullableBoolean: { type: 'boolean', @@ -152,7 +152,7 @@ export default createRule({ allowNullableObject: { type: 'boolean', description: - 'Whether to allow nullable `object`s in a boolean context.', + 'Whether to allow nullable `object`s, `symbol`s, and functions in a boolean context.', }, allowNullableString: { type: 'boolean', @@ -161,14 +161,16 @@ export default createRule({ }, allowNumber: { type: 'boolean', - description: 'Whether to allow `number` in a boolean context.', + description: 'Whether to allow `number`s in a boolean context.', }, allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing: { type: 'boolean', + description: + 'Unless this is set to `true`, the rule will error on every file whose `tsconfig.json` does _not_ have the `strictNullChecks` compiler option (or `strict`) set to `true`.', }, allowString: { type: 'boolean', - description: 'Whether to allow `string` in a boolean context.', + description: 'Whether to allow `string`s in a boolean context.', }, }, }, diff --git a/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot b/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot index ab5b34c1d89c..0a601ac8f34d 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/class-literal-property-style.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which literal class member syntax to prefer.", "enum": ["fields", "getters"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['fields' | 'getters']; +type Options = [ + /** Which literal class member syntax to prefer. */ + | 'getters' + /** Which literal class member syntax to prefer. */ + | 'fields', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot b/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot index ccecd0a0f6a9..fd93a8fc8c4f 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/class-methods-use-this.shot @@ -10,18 +10,18 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "properties": { "enforceForClassFields": { "default": true, - "description": "Enforces that functions used as instance field initializers utilize \`this\`", + "description": "Enforces that functions used as instance field initializers utilize \`this\`.", "type": "boolean" }, "exceptMethods": { - "description": "Allows specified method names to be ignored with this rule", + "description": "Allows specified method names to be ignored with this rule.", "items": { "type": "string" }, "type": "array" }, "ignoreClassesThatImplementAnInterface": { - "description": "Ignore classes that specifically implement some interface", + "description": "Makes the rule ignore class members that are defined within a class that \`implements\` a type", "oneOf": [ { "description": "Ignore all classes that implement an interface", @@ -48,13 +48,13 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { - /** Enforces that functions used as instance field initializers utilize \`this\` */ + /** Enforces that functions used as instance field initializers utilize \`this\`. */ enforceForClassFields?: boolean; - /** Allows specified method names to be ignored with this rule */ + /** Allows specified method names to be ignored with this rule. */ exceptMethods?: string[]; - /** Ignore classes that specifically implement some interface */ + /** Makes the rule ignore class members that are defined within a class that \`implements\` a type */ ignoreClassesThatImplementAnInterface?: /** - * Ignore classes that specifically implement some interface + * Makes the rule ignore class members that are defined within a class that \`implements\` a type * Ignore all classes that implement an interface */ | boolean diff --git a/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot b/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot index 339f564088a9..7f40a340e498 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/consistent-generic-constructors.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which constructor call syntax to prefer.", "enum": ["constructor", "type-annotation"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['constructor' | 'type-annotation']; +type Options = [ + /** Which constructor call syntax to prefer. */ + | 'type-annotation' + /** Which constructor call syntax to prefer. */ + | 'constructor', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot b/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot index d498aa9d3571..e6aac3062fc5 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/consistent-indexed-object-style.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which indexed object syntax to prefer.", "enum": ["index-signature", "record"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['index-signature' | 'record']; +type Options = [ + /** Which indexed object syntax to prefer. */ + | 'record' + /** Which indexed object syntax to prefer. */ + | 'index-signature', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot b/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot index 0a7217423843..a47225168222 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/consistent-type-definitions.shot @@ -6,6 +6,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos [ { + "description": "Which type definition syntax to prefer.", "enum": ["interface", "type"], "type": "string" } @@ -14,6 +15,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: -type Options = ['interface' | 'type']; +type Options = [ + /** Which type definition syntax to prefer. */ + | 'type' + /** Which type definition syntax to prefer. */ + | 'interface', +]; " `; diff --git a/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot b/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot index 38813f579a5e..0606e4d377b1 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/explicit-member-accessibility.shot @@ -30,7 +30,8 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "accessibility": { - "$ref": "#/items/0/$defs/accessibilityLevel" + "$ref": "#/items/0/$defs/accessibilityLevel", + "description": "Which accessibility modifier is required to exist or not exist." }, "ignoredMethodNames": { "description": "Specific method names that may be ignored.", @@ -41,6 +42,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos }, "overrides": { "additionalProperties": false, + "description": "Changes to required accessibility modifiers for specific kinds of class members.", "properties": { "accessors": { "$ref": "#/items/0/$defs/accessibilityLevel" @@ -78,9 +80,11 @@ type AccessibilityLevel = type Options = [ { + /** Which accessibility modifier is required to exist or not exist. */ accessibility?: AccessibilityLevel; /** Specific method names that may be ignored. */ ignoredMethodNames?: string[]; + /** Changes to required accessibility modifiers for specific kinds of class members. */ overrides?: { accessors?: AccessibilityLevel; constructors?: AccessibilityLevel; diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot b/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot index a02fca83275d..c6610bd2980c 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-invalid-void-type.shot @@ -16,9 +16,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "description": "Whether \`void\` can be used as a valid value for generic type parameters.", "oneOf": [ { + "description": "Whether \`void\` can be used as a valid value for all generic type parameters.", "type": "boolean" }, { + "description": "Allowlist of types that may accept \`void\` as a generic type parameter.", "items": { "type": "string" }, @@ -40,10 +42,13 @@ type Options = [ /** Whether a \`this\` parameter of a function may be \`void\`. */ allowAsThisParameter?: boolean; /** Whether \`void\` can be used as a valid value for generic type parameters. */ - allowInGenericTypeArguments?: - | [string, ...string[]] - /** Whether \`void\` can be used as a valid value for generic type parameters. */ - | boolean; + allowInGenericTypeArguments?: /** + * Whether \`void\` can be used as a valid value for generic type parameters. + * Whether \`void\` can be used as a valid value for all generic type parameters. + */ + | boolean + /** Allowlist of types that may accept \`void\` as a generic type parameter. */ + | [string, ...string[]]; }, ]; " diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot b/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot index e0d897012c0a..4ce87848cced 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-misused-promises.shot @@ -9,6 +9,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "checksConditionals": { + "description": "Whether to warn when a Promise is provided to conditional statements.", "type": "boolean" }, "checksSpreads": { @@ -16,12 +17,15 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "boolean" }, "checksVoidReturn": { + "description": "Whether to warn when a Promise is returned from a function typed as returning \`void\`.", "oneOf": [ { + "description": "Whether to disable checking all asynchronous functions.", "type": "boolean" }, { "additionalProperties": false, + "description": "Which forms of functions may have checking disabled.", "properties": { "arguments": { "description": "Disables checking an asynchronous function passed as argument where the parameter type expects a function that returns \`void\`.", @@ -62,10 +66,17 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { + /** Whether to warn when a Promise is provided to conditional statements. */ checksConditionals?: boolean; /** Whether to warn when \`...\` spreading a \`Promise\`. */ checksSpreads?: boolean; - checksVoidReturn?: + /** Whether to warn when a Promise is returned from a function typed as returning \`void\`. */ + checksVoidReturn?: /** + * Whether to warn when a Promise is returned from a function typed as returning \`void\`. + * Whether to disable checking all asynchronous functions. + */ + | boolean + /** Which forms of functions may have checking disabled. */ | { /** Disables checking an asynchronous function passed as argument where the parameter type expects a function that returns \`void\`. */ arguments?: boolean; @@ -79,8 +90,7 @@ type Options = [ returns?: boolean; /** Disables checking an asynchronous function used as a variable whose return type is a function that returns \`void\`. */ variables?: boolean; - } - | boolean; + }; }, ]; " diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot index 55bec533996f..7c4fb5932293 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-imports.shot @@ -22,7 +22,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "array" }, "allowTypeImports": { - "description": "Disallow value imports, but allow type-only imports.", + "description": "Whether to allow type-only imports for a path.", "type": "boolean" }, "importNames": { @@ -69,7 +69,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "array" }, "allowTypeImports": { - "description": "Disallow value imports, but allow type-only imports.", + "description": "Whether to allow type-only imports for a path.", "type": "boolean" }, "importNames": { @@ -119,7 +119,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "uniqueItems": true }, "allowTypeImports": { - "description": "Disallow value imports, but allow type-only imports.", + "description": "Whether to allow type-only imports for a path.", "type": "boolean" }, "caseSensitive": { @@ -173,7 +173,7 @@ type Options = | ( | { allowImportNames?: string[]; - /** Disallow value imports, but allow type-only imports. */ + /** Whether to allow type-only imports for a path. */ allowTypeImports?: boolean; importNames?: string[]; message?: string; @@ -187,7 +187,7 @@ type Options = paths?: ( | { allowImportNames?: string[]; - /** Disallow value imports, but allow type-only imports. */ + /** Whether to allow type-only imports for a path. */ allowTypeImports?: boolean; importNames?: string[]; message?: string; @@ -199,7 +199,7 @@ type Options = | { allowImportNamePattern?: string; allowImportNames?: [string, ...string[]]; - /** Disallow value imports, but allow type-only imports. */ + /** Whether to allow type-only imports for a path. */ allowTypeImports?: boolean; caseSensitive?: boolean; group: [string, ...string[]]; diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot index 845262dabe82..bd7867ed79e8 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-restricted-types.shot @@ -10,24 +10,24 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "banConfig": { "oneOf": [ { - "description": "Bans the type with the default message", + "description": "Bans the type with the default message.", "enum": [true], "type": "boolean" }, { - "description": "Bans the type with a custom message", + "description": "Bans the type with a custom message.", "type": "string" }, { "additionalProperties": false, - "description": "Bans a type", + "description": "Bans a type.", "properties": { "fixWith": { "description": "Type to autofix replace with. Note that autofixers can be applied automatically - so you need to be careful with this option.", "type": "string" }, "message": { - "description": "Custom error message", + "description": "Custom error message.", "type": "string" }, "suggest": { @@ -49,6 +49,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": { "$ref": "#/items/0/$defs/banConfig" }, + "description": "An object whose keys are the types you want to ban, and the values are error messages.", "type": "object" } }, @@ -60,22 +61,23 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos # TYPES: type BanConfig = - /** Bans a type */ + /** Bans a type. */ | { /** Type to autofix replace with. Note that autofixers can be applied automatically - so you need to be careful with this option. */ fixWith?: string; - /** Custom error message */ + /** Custom error message. */ message?: string; /** Types to suggest replacing with. */ suggest?: string[]; } - /** Bans the type with a custom message */ + /** Bans the type with a custom message. */ | string - /** Bans the type with the default message */ + /** Bans the type with the default message. */ | true; type Options = [ { + /** An object whose keys are the types you want to ban, and the values are error messages. */ types?: { [k: string]: BanConfig; }; diff --git a/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot b/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot index a094b1776731..192552d4fd41 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/no-use-before-define.shot @@ -15,6 +15,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "allowNamedExports": { + "description": "Whether to ignore named exports.", "type": "boolean" }, "classes": { @@ -54,6 +55,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ | 'nofunc' | { + /** Whether to ignore named exports. */ allowNamedExports?: boolean; /** Whether to ignore references to class declarations. */ classes?: boolean; diff --git a/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot b/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot index ca0e2597bf59..1769b32c5ce9 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/prefer-destructuring.shot @@ -54,9 +54,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos { "properties": { "enforceForDeclarationWithTypeAnnotation": { + "description": "Whether to enforce destructuring on variable declarations with type annotations.", "type": "boolean" }, "enforceForRenamedProperties": { + "description": "Whether to enforce destructuring that use a different variable name than the property name.", "type": "boolean" } }, @@ -85,7 +87,9 @@ type Options = [ } ), { + /** Whether to enforce destructuring on variable declarations with type annotations. */ enforceForDeclarationWithTypeAnnotation?: boolean; + /** Whether to enforce destructuring that use a different variable name than the property name. */ enforceForRenamedProperties?: boolean; [k: string]: unknown; }, diff --git a/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot b/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot index 7afce381e977..58a4820086c3 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/prefer-nullish-coalescing.shot @@ -24,23 +24,29 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "description": "Whether to ignore all (\`true\`) or some (an object with properties) primitive types.", "oneOf": [ { + "description": "Which primitives types may be ignored.", "properties": { "bigint": { + "description": "Ignore bigint primitive types.", "type": "boolean" }, "boolean": { + "description": "Ignore boolean primitive types.", "type": "boolean" }, "number": { + "description": "Ignore number primitive types.", "type": "boolean" }, "string": { + "description": "Ignore string primitive types.", "type": "boolean" } }, "type": "object" }, { + "description": "Ignore all primitive types.", "enum": [true], "type": "boolean" } @@ -67,16 +73,23 @@ type Options = [ /** Whether to ignore any logical or expressions that are part of a mixed logical expression (with \`&&\`). */ ignoreMixedLogicalExpressions?: boolean; /** Whether to ignore all (\`true\`) or some (an object with properties) primitive types. */ - ignorePrimitives?: - | true - /** Whether to ignore all (\`true\`) or some (an object with properties) primitive types. */ - | { + ignorePrimitives?: /** + * Whether to ignore all (\`true\`) or some (an object with properties) primitive types. + * Which primitives types may be ignored. + */ + | { + /** Ignore bigint primitive types. */ bigint?: boolean; + /** Ignore boolean primitive types. */ boolean?: boolean; + /** Ignore number primitive types. */ number?: boolean; + /** Ignore string primitive types. */ string?: boolean; [k: string]: unknown; - }; + } + /** Ignore all primitive types. */ + | true; /** Whether to ignore any ternary expressions that could be simplified by using the nullish coalescing operator. */ ignoreTernaryTests?: boolean; }, diff --git a/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot b/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot index 2b5fe0203a1a..32232ad1ab67 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/sort-type-constituents.shot @@ -9,15 +9,15 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "caseSensitive": { - "description": "Whether to sort using case sensitive sorting.", + "description": "Whether to sort using case sensitive string comparisons.", "type": "boolean" }, "checkIntersections": { - "description": "Whether to check intersection types.", + "description": "Whether to check intersection types (\`&\`).", "type": "boolean" }, "checkUnions": { - "description": "Whether to check union types.", + "description": "Whether to check union types (\`|\`).", "type": "boolean" }, "groupOrder": { @@ -51,11 +51,11 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { - /** Whether to sort using case sensitive sorting. */ + /** Whether to sort using case sensitive string comparisons. */ caseSensitive?: boolean; - /** Whether to check intersection types. */ + /** Whether to check intersection types (\`&\`). */ checkIntersections?: boolean; - /** Whether to check union types. */ + /** Whether to check union types (\`|\`). */ checkUnions?: boolean; /** Ordering of the groups. */ groupOrder?: ( diff --git a/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot b/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot index 5c52af177f3d..77591c6228fc 100644 --- a/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot +++ b/packages/eslint-plugin/tests/schema-snapshots/strict-boolean-expressions.shot @@ -9,7 +9,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "additionalProperties": false, "properties": { "allowAny": { - "description": "Whether to allow \`any\` in a boolean context.", + "description": "Whether to allow \`any\`s in a boolean context.", "type": "boolean" }, "allowNullableBoolean": { @@ -25,7 +25,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "boolean" }, "allowNullableObject": { - "description": "Whether to allow nullable \`object\`s in a boolean context.", + "description": "Whether to allow nullable \`object\`s, \`symbol\`s, and functions in a boolean context.", "type": "boolean" }, "allowNullableString": { @@ -33,14 +33,15 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos "type": "boolean" }, "allowNumber": { - "description": "Whether to allow \`number\` in a boolean context.", + "description": "Whether to allow \`number\`s in a boolean context.", "type": "boolean" }, "allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing": { + "description": "Unless this is set to \`true\`, the rule will error on every file whose \`tsconfig.json\` does _not_ have the \`strictNullChecks\` compiler option (or \`strict\`) set to \`true\`.", "type": "boolean" }, "allowString": { - "description": "Whether to allow \`string\` in a boolean context.", + "description": "Whether to allow \`string\`s in a boolean context.", "type": "boolean" } }, @@ -53,7 +54,7 @@ exports[`Rule schemas should be convertible to TS types for documentation purpos type Options = [ { - /** Whether to allow \`any\` in a boolean context. */ + /** Whether to allow \`any\`s in a boolean context. */ allowAny?: boolean; /** Whether to allow nullable \`boolean\`s in a boolean context. */ allowNullableBoolean?: boolean; @@ -61,14 +62,15 @@ type Options = [ allowNullableEnum?: boolean; /** Whether to allow nullable \`number\`s in a boolean context. */ allowNullableNumber?: boolean; - /** Whether to allow nullable \`object\`s in a boolean context. */ + /** Whether to allow nullable \`object\`s, \`symbol\`s, and functions in a boolean context. */ allowNullableObject?: boolean; /** Whether to allow nullable \`string\`s in a boolean context. */ allowNullableString?: boolean; - /** Whether to allow \`number\` in a boolean context. */ + /** Whether to allow \`number\`s in a boolean context. */ allowNumber?: boolean; + /** Unless this is set to \`true\`, the rule will error on every file whose \`tsconfig.json\` does _not_ have the \`strictNullChecks\` compiler option (or \`strict\`) set to \`true\`. */ allowRuleToRunWithoutStrictNullChecksIKnowWhatIAmDoing?: boolean; - /** Whether to allow \`string\` in a boolean context. */ + /** Whether to allow \`string\`s in a boolean context. */ allowString?: boolean; }, ]; diff --git a/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts b/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts index 3c44aae99a0c..29ca8a6e66c4 100644 --- a/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts +++ b/packages/website/plugins/generated-rule-docs/RuleDocsPage.ts @@ -3,7 +3,7 @@ import { fromMarkdown } from 'mdast-util-from-markdown'; import type * as unist from 'unist'; import type { VFileWithStem } from '../utils/rules'; -import { findH2Index } from '../utils/rules'; +import { findHeadingIndex } from '../utils/rules'; export interface RequiredHeadingIndices { howToUse: number; @@ -72,9 +72,13 @@ export class RuleDocsPage { #recreateHeadingIndices(): RequiredHeadingIndices { return { - howToUse: findH2Index(this.#children, requiredHeadingNames[0]), - options: findH2Index(this.#children, requiredHeadingNames[1]), - whenNotToUseIt: findH2Index(this.#children, requiredHeadingNames[2]), + howToUse: findHeadingIndex(this.#children, 2, requiredHeadingNames[0]), + options: findHeadingIndex(this.#children, 2, requiredHeadingNames[1]), + whenNotToUseIt: findHeadingIndex( + this.#children, + 2, + requiredHeadingNames[2], + ), }; } } diff --git a/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts b/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts index 939e50e81704..aef53121a1fe 100644 --- a/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts +++ b/packages/website/plugins/generated-rule-docs/createRuleDocsPage.ts @@ -3,7 +3,7 @@ import type * as mdast from 'mdast'; import type * as unist from 'unist'; import type { VFileWithStem } from '../utils/rules'; -import { findH2Index } from '../utils/rules'; +import { findHeadingIndex } from '../utils/rules'; import type { HeadingName } from './RuleDocsPage'; import { requiredHeadingNames, RuleDocsPage } from './RuleDocsPage'; @@ -13,7 +13,7 @@ export function createRuleDocsPage( rule: Readonly, ): RuleDocsPage { const headingIndices = requiredHeadingNames.map(headingName => - findH2Index(children, headingName), + findHeadingIndex(children, 2, headingName), ); function insertIfMissing( diff --git a/packages/website/plugins/generated-rule-docs/index.ts b/packages/website/plugins/generated-rule-docs/index.ts index 85c425cb38e4..088c53e1b534 100644 --- a/packages/website/plugins/generated-rule-docs/index.ts +++ b/packages/website/plugins/generated-rule-docs/index.ts @@ -9,6 +9,7 @@ import { insertBaseRuleReferences } from './insertions/insertBaseRuleReferences' import { insertNewRuleReferences } from './insertions/insertNewRuleReferences'; import { insertResources } from './insertions/insertResources'; import { insertRuleDescription } from './insertions/insertRuleDescription'; +import { insertRuleOptions } from './insertions/insertRuleOptions'; import { insertWhenNotToUseIt } from './insertions/insertWhenNotToUseIt'; import { removeSourceCodeNotice } from './removeSourceCodeNotice'; @@ -34,6 +35,7 @@ export const generatedRuleDocs: Plugin = () => { insertWhenNotToUseIt(page); insertResources(page); + insertRuleOptions(page); addESLintHashToCodeBlocksMeta(page, eslintrc); }; }; diff --git a/packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts b/packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts new file mode 100644 index 000000000000..466735f20cd3 --- /dev/null +++ b/packages/website/plugins/generated-rule-docs/insertions/insertRuleOptions.ts @@ -0,0 +1,125 @@ +import type { JSONSchema4 } from '@typescript-eslint/utils/json-schema'; +import type { Node } from 'unist'; + +import { nodeIsHeading, nodeIsMdxFlowExpression } from '../../utils/nodes'; +import { findHeadingIndex } from '../../utils/rules'; +import type { RuleDocsPage } from '../RuleDocsPage'; + +const knownSkippedRules = new Set([ + 'array-type', + 'ban-ts-comment', + 'member-ordering', +]); + +const emptyOptionDefaults = new Map([ + ['boolean', false], + ['array', []], +]); + +export function insertRuleOptions(page: RuleDocsPage): void { + if ( + knownSkippedRules.has(page.file.stem) || + !Array.isArray(page.rule.meta.schema) + ) { + return; + } + + const optionProperties = getOptionProperties( + (page.rule.meta.schema as JSONSchema4[]).at(0), + ); + + if (!optionProperties) { + return; + } + + const defaultOptions = (page.rule.defaultOptions[0] ?? {}) as Record< + string, + unknown + >; + + for (const [optionName, option] of Object.entries(optionProperties)) { + if (!option.description) { + if (!page.rule.meta.docs.extendsBaseRule) { + throw new Error(`Missing description for option ${optionName}.`); + } + return; + } + + const existingHeadingIndex = findHeadingIndex( + page.children, + 3, + node => node.type === 'inlineCode' && node.value === optionName, + ); + if (existingHeadingIndex === -1) { + if (!page.rule.meta.docs.extendsBaseRule) { + throw new Error(`Couldn't find h3 for option ${optionName}.`); + } + continue; + } + + const commentInsertionIndex = findCommentIndexForOption( + page.children, + existingHeadingIndex, + ); + if (commentInsertionIndex === -1) { + throw new Error( + `[${page.file.stem}] Could not find ${OPTION_COMMENT} under option heading ${optionName}.`, + ); + } + + const defaultValue = + defaultOptions[optionName] ?? emptyOptionDefaults.get(option.type); + + page.spliceChildren( + commentInsertionIndex, + 0, + defaultValue !== undefined + ? `${option.description} Default: \`${JSON.stringify(defaultValue)}\`.` + : option.description, + ); + } +} + +const OPTION_COMMENT = `/* insert option description */`; + +function findCommentIndexForOption( + children: readonly Node[], + headingIndex: number, +): number { + for (let i = headingIndex + 1; i < children.length; i += 1) { + const child = children[i]; + if (nodeIsMdxFlowExpression(child) && child.value === OPTION_COMMENT) { + return i; + } + + if (nodeIsHeading(child)) { + break; + } + } + + return -1; +} + +function getOptionProperties( + options: JSONSchema4 | undefined, +): Record | undefined { + if (!options) { + return undefined; + } + + if (options.type === 'object') { + return options.properties; + } + + if (options.oneOf) { + return options.oneOf.reduce>( + (previous, next) => ({ + ...previous, + ...getOptionProperties(next), + }), + {}, + ); + } + + return undefined; +} diff --git a/packages/website/plugins/utils/nodes.ts b/packages/website/plugins/utils/nodes.ts index 5d7d1494a45c..3f1e5c995268 100644 --- a/packages/website/plugins/utils/nodes.ts +++ b/packages/website/plugins/utils/nodes.ts @@ -1,4 +1,5 @@ import type * as mdast from 'mdast'; +import type { MdxFlowExpression } from 'mdast-util-mdx'; import type * as unist from 'unist'; export function nodeIsCode(node: unist.Node): node is mdast.Code { @@ -9,6 +10,12 @@ export function nodeIsHeading(node: unist.Node): node is mdast.Heading { return node.type === 'heading'; } +export function nodeIsMdxFlowExpression( + node: unist.Node, +): node is MdxFlowExpression { + return node.type === 'mdxFlowExpression'; +} + export function nodeIsParent(node: unist.Node): node is unist.Parent { return 'children' in node; } diff --git a/packages/website/plugins/utils/rules.ts b/packages/website/plugins/utils/rules.ts index 02130f2e28db..508616497146 100644 --- a/packages/website/plugins/utils/rules.ts +++ b/packages/website/plugins/utils/rules.ts @@ -4,6 +4,7 @@ import * as path from 'node:path'; import type { ESLintPluginRuleModule } from '@typescript-eslint/eslint-plugin/use-at-your-own-risk/rules'; import type { RuleModule } from '@typescript-eslint/utils/ts-eslint'; import * as lz from 'lz-string'; +import type * as mdast from 'mdast'; import type * as unist from 'unist'; import type { VFile } from 'vfile'; @@ -68,16 +69,22 @@ export function isVFileWithStem(file: VFile): file is VFileWithStem { return !!file.stem; } -export function findH2Index( - children: unist.Node[], - headingName: string, +export function findHeadingIndex( + children: readonly unist.Node[], + depth: 2 | 3, + contents: string | ((node: mdast.PhrasingContent) => boolean), ): number { + const childMatch = + typeof contents === 'string' + ? (node: mdast.PhrasingContent): boolean => + node.type === 'text' && node.value === contents + : contents; + return children.findIndex( node => nodeIsHeading(node) && - node.depth === 2 && + node.depth === depth && node.children.length === 1 && - node.children[0].type === 'text' && - node.children[0].value === headingName, + childMatch(node.children[0]), ); }