8000 docs: standardized rule docs heading and option-less Options (#4367) · lonyele/typescript-eslint@1c8895f · GitHub
[go: up one dir, main page]
Skip to content

Commit 1c8895f

Browse files
Josh Goldberglonyele
Josh Goldberg
authored and
lonyele
committed
docs: standardized rule docs heading and option-less Options (typescript-eslint#4367)
1 parent 532bc34 commit 1c8895f

File tree

125 files changed

+710
-140
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

125 files changed

+710
-140
lines changed

‎packages/eslint-plugin/docs/rules/TEMPLATE.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# `your-rule-name`
2+
3+
Your rule description here.
4+
5+
## Rule Details
6+
7+
To fill out: tell us more about this rule.
8+
9+
<!--tabs-->
10+
11+
### ❌ Incorrect
12+
13+
```ts
14+
// To fill out: incorrect code
15+
```
16+
17+
### ✅ Correct
18+
19+
```ts
20+
// To fill out: correct code
21+
```
22+
23+
## Options
24+
25+
```jsonc
26+
// .eslintrc.json
27+
{
28+
"rules": {
29+
"@typescript-eslint/your-rule-name": "error"
30+
}
31+
}
32+
```
33+
34+
If not configurable: This rule is not configurable.
35+
36+
If configurable...
37+
38+
```ts
39+
type Options = {
40+
someOption?: boolean;
41+
};
42+
43+
const defaultOptions: Options = {
44+
someOption: false,
45+
};
46+
```
47+
48+
## When Not To Use It
49+
50+
To fill out: why wouldn't you want to use this rule?
51+
For example if this rule requires a feature released in a certain TS version.
52+
53+
## Attributes
54+
55+
- [ ] ✅ Recommended
56+
- [ ] 🔧 Fixable
57+
- [ ] 💭 Requires type information

‎packages/eslint-plugin/docs/rules/adjacent-overload-signatures.md

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require that member overloads be consecutive (`adjacent-overload-signatures`)
1+
# `adjacent-overload-signatures`
2+
3+
Require that member overloads be consecutive.
24

35
Grouping overloaded members together can improve readability of the code.
46

@@ -82,6 +84,19 @@ export function foo(n: number): void;
8284
export function foo(sn: string | number): void;
8385
```
8486

87+
## Options
88+
89+
```jsonc
90+
// .eslintrc.json
91+
{
92+
"rules": {
93+
"@typescript-eslint/adjacent-overload-signatures": "error"
94+
}
95+
}
96+
```
97+
98+
This rule is not configurable.
99+
85100
## When Not To Use It
86101

87102
If you don't care about the general structure of the code, then you will not need this rule.

‎packages/eslint-plugin/docs/rules/array-type.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Requires using either `T[]` or `Array<T>` for arrays (`array-type`)
1+
# `array-type`
2+
3+
Requires using either `T[]` or `Array<T>` for arrays.
24

35
Using the same style for array definitions across your codebase makes it easier for your developers to read and understand the types.
46

‎packages/eslint-plugin/docs/rules/await-thenable.md

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallows awaiting a value that is not a Thenable (`await-thenable`)
1+
# `await-thenable`
2+
3+
Disallows awaiting a value that is not a Thenable.
24

35
This rule disallows awaiting a value that is not a "Thenable" (an object which has `then` method, such as a Promise).
46
While it is valid JavaScript to await a non-`Promise`-like value (it will resolve immediately), this pattern is often a programmer error, such as forgetting to add parenthesis to call a function that returns a Promise.
@@ -27,6 +29,19 @@ const createValue = async () => 'value';
2729
await createValue();
2830
```
2931

32+
## Options
33+
34+
```jsonc
35+
// .eslintrc.json
36+
{
37+
"rules": {
38+
"@typescript-eslint/await-thenable": "error"
39+
}
40+
}
41+
```
42+
43+
This rule is not configurable.
44+
3045
## When Not To Use It
3146

3247
If you want to allow code to `await` non-Promise values.

‎packages/eslint-plugin/docs/rules/ban-ts-comment.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Bans `@ts-<directive>` comments from being used or requires descriptions after directive (`ban-ts-comment`)
1+
# `ban-ts-comment`
2+
3+
Bans `@ts-<directive>` comments from being used or requires descriptions after directive.
24

35
TypeScript provides several directive comments that can be used to alter how it processes files.
46
Using these to suppress TypeScript Compiler Errors reduces the effectiveness of TypeScript overall.

‎packages/eslint-plugin/docs/rules/ban-tslint-comment.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Bans `// tslint:<rule-flag>` comments from being used (`ban-tslint-comment`)
1+
# `ban-tslint-comment`
2+
3+
Bans `// tslint:<rule-flag>` comments from being used.
24

35
Useful when migrating from TSLint to ESLint. Once TSLint has been removed, this rule helps locate TSLint annotations (e.g. `// tslint:disable`).
46

‎packages/eslint-plugin/docs/rules/ban-types.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Bans specific types from being used (`ban-types`)
1+
# `ban-types`
2+
3+
Bans specific types from being used.
24

35
Some builtin types have aliases, some types are considered dangerous or harmful.
46
It's often a good idea to ban certain types to help with consistency and safety.

‎packages/eslint-plugin/docs/rules/brace-style.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforce consistent brace style for blocks (`brace-style`)
1+
# `brace-style`
2+
3+
Enforce consistent brace style for blocks.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/class-literal-property-style.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Ensures that literals on classes are exposed in a consistent style (`class-literal-property-style`)
1+
# `class-literal-property-style`
2+
3+
Ensures that literals on classes are exposed in a consistent style.
24

35
When writing TypeScript applications, it's typically safe to store literal values on classes using fields with the `readonly` modifier to prevent them from being reassigned.
46
When writing TypeScript libraries that could be used by JavaScript users however, it's typically safer to expose these literals using `getter`s, since the `readonly` modifier is enforced at compile type.

‎packages/eslint-plugin/docs/rules/comma-dangle.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require or disallow trailing comma (`comma-dangle`)
1+
# `comma-dangle`
2+
3+
Require or disallow trailing comma.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/comma-spacing.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces consistent spacing before and after commas (`comma-spacing`)
1+
# `comma-spacing`
2+
3+
Enforces consistent spacing before and after commas.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/consistent-indexed-object-style.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforce or disallow the use of the record type (`consistent-indexed-object-style`)
1+
# `consistent-indexed-object-style`
2+
3+
Enforce or disallow the use of the record type.
24

35
TypeScript supports defining object show keys can be flexible using an index signature. TypeScript also has a builtin type named `Record` to create an empty object defining only an index signature. For example, the following types are equal:
46

‎packages/eslint-plugin/docs/rules/consistent-type-assertions.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces consistent usage of type assertions (`consistent-type-assertions`)
1+
# `consistent-type-assertions`
2+
3+
Enforces consistent usage of type assertions.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/consistent-type-definitions.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Consistent with type definition either `interface` or `type` (`consistent-type-definitions`)
1+
# `consistent-type-definitions`
2+
3+
Consistent with type definition either `interface` or `type`.
24

35
There are two ways to define a type.
46

‎packages/eslint-plugin/docs/rules/consistent-type-exports.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces consistent usage of type exports (`consistent-type-exports`)
1+
# `consistent-type-exports`
2+
3+
Enforces consistent usage of type exports.
24

35
TypeScript 3.8 added support for type-only exports.
46

‎packages/eslint-plugin/docs/rules/consistent-type-imports.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces consistent usage of type imports (`consistent-type-imports`)
1+
# `consistent-type-imports`
2+
3+
Enforces consistent usage of type imports.
24

35
TypeScript 3.8 added support for type-only imports.
46
Type-only imports allow you to specify that an import can only be used in a type location, allowing certain optimizations within compilers.

‎packages/eslint-plugin/docs/rules/default-param-last.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforce default parameters to be last (`default-param-last`)
1+
# `default-param-last`
2+
3+
Enforce default parameters to be last.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/dot-notation.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# enforce dot notation whenever possible (`dot-notation`)
1+
# `dot-notation`
2+
3+
enforce dot notation whenever possible.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/explicit-function-return-type.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require explicit return types on functions and class methods (`explicit-function-return-type`)
1+
# `explicit-function-return-type`
2+
3+
Require explicit return types on functions and class methods.
24

35
Explicit types for function return values makes it clear to any calling code what type is returned.
46
This ensures that the return value is assigned to a variable of the correct type; or in the case

‎packages/eslint-plugin/docs/rules/explicit-member-accessibility.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require explicit accessibility modifiers on class properties and methods (`explicit-member-accessibility`)
1+
# `explicit-member-accessibility`
2+
3+
Require explicit accessibility modifiers on class properties and methods.
24

35
Leaving off accessibility modifier and making everything public can make
46
your interface hard to use by others.

‎packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require explicit return and argument types on exported functions' and classes' public class methods (`explicit-module-boundary-types`)
1+
# `explicit-module-boundary-types`
2+
3+
Require explicit return and argument types on exported functions' and classes' public class methods.
24

35
Explicit types for function return values and arguments makes it clear to any calling code what is the module boundary's input and output.
46

‎packages/eslint-plugin/docs/rules/func-call-spacing.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require or disallow spacing between function identifiers and their invocations (`func-call-spacing`)
1+
# `func-call-spacing`
2+
3+
Require or disallow spacing between function identifiers and their invocations.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/indent.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforce consistent indentation (`indent`)
1+
# `indent`
2+
3+
Enforce consistent indentation.
24

35
## Warning
46

‎packages/eslint-plugin/docs/rules/init-declarations.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# require or disallow initialization in variable declarations (`init-declarations`)
1+
# `init-declarations`
2+
3+
require or disallow initialization in variable declarations.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/keyword-spacing.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforce consistent spacing before and after keywords (`keyword-spacing`)
1+
# `keyword-spacing`
2+
3+
Enforce consistent spacing before and after keywords.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/lines-between-class-members.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require or disallow an empty line between class members (`lines-between-class-members`)
1+
# `lines-between-class-members`
2+
3+
Require or disallow an empty line between class members.
24

35
This rule improves readability by enforcing lines between class members. It will not check empty lines before the first member and after the last member. This rule require or disallow an empty line between class members.
46

‎packages/eslint-plugin/docs/rules/member-delimiter-style.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require a specific member delimiter style for interfaces and type literals (`member-delimiter-style`)
1+
# `member-delimiter-style`
2+
3+
Require a specific member delimiter style for interfaces and type literals.
24

35
Enforces a consistent member delimiter style in interfaces and type literals. There are three member delimiter styles primarily used in TypeScript:
46

‎packages/eslint-plugin/docs/rules/member-ordering.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Require a consistent member declaration order (`member-ordering`)
1+
# `member-ordering`
2+
3+
Require a consistent member declaration order.
24

35
A consistent ordering of fields, methods and constructors can make interfaces, type literals, classes and class expressions easier to read, navigate and edit.
46

‎packages/eslint-plugin/docs/rules/method-signature-style.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces using a particular method signature syntax. (`method-signature-style`)
1+
# `method-signature-style`
2+
3+
Enforces using a particular method signature syntax..
24

35
There are two ways to define an object/interface function property.
46

‎packages/eslint-plugin/docs/rules/naming-convention.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces naming conventions for everything across a codebase (`naming-convention`)
1+
# `naming-convention`
2+
3+
Enforces naming conventions for everything across a codebase.
24

35
Enforcing naming conventions helps keep the codebase consistent, and reduces overhead when thinking about how to name a variable.
46
Additionally, a well-designed style guide can help communicate intent, such as by enforcing all private properties begin with an `_`, and all global-level constants are written in `UPPER_CASE`.

‎packages/eslint-plugin/docs/rules/no-array-constructor.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallow generic `Array` constructors (`no-array-constructor`)
1+
# `no-array-constructor`
2+
3+
Disallow generic `Array` constructors.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/no-base-to-string.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Requires that `.toString()` is only called on objects which provide useful information when stringified (`no-base-to-string`)
1+
# `no-base-to-string`
2+
3+
Requires that `.toString()` is only called on objects which provide useful information when stringified.
24

35
JavaScript will call `toString()` on an object when it is converted to a string, such as when `+` adding to a string or in `${}` template literals.
46

‎packages/eslint-plugin/docs/rules/no-confusing-non-null-assertion.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallow non-null assertion in locations that may be confusing (`no-confusing-non-null-assertion`)
1+
# `no-confusing-non-null-assertion`
2+
3+
Disallow non-null assertion in locations that may be confusing.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/no-confusing-void-expression.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Requires expressions of type void to appear in statement position (`no-confusing-void-expression`)
1+
# `no-confusing-void-expression`
2+
3+
Requires expressions of type void to appear in statement position.
24

35
Returning the results of an expression whose type is void can be misleading.
46
Attempting to do so is likely a symptom of expecting a different return type from a function.

‎packages/eslint-plugin/docs/rules/no-dupe-class-members.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallow duplicate class members (`no-dupe-class-members`)
1+
# `no-dupe-class-members`
2+
3+
Disallow duplicate class members.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/no-duplicate-imports.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallow duplicate imports (`no-duplicate-imports`)
1+
# `no-duplicate-imports`
2+
3+
Disallow duplicate imports.
24

35
## Rule Details
46

‎packages/eslint-plugin/docs/rules/no-dynamic-delete.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallow the delete operator with computed key expressions (`no-dynamic-delete`)
1+
# `no-dynamic-delete`
2+
3+
Disallow the delete operator with computed key expressions.
24

35
Deleting dynamically computed keys can be dangerous and in some cases not well optimized.
46

‎packages/eslint-plugin/docs/rules/no-empty-function.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Disallow empty functions (`no-empty-function`)
1+
# `no-empty-function`
2+
3+
Disallow empty functions.
24

35
## Rule Details
46

0 commit comments

Comments
 (0)
0