Skip to content

Commit 3c2a7fe

Browse files
Rel1cxRel1cx
authored
docs: correct outdated rule docs to match current sources (#1920)
1 parent 0a74227 commit 3c2a7fe

46 files changed

Lines changed: 334 additions & 273 deletions

Some content is hidden

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

‎docs/rule-feature-system.md‎

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Rule Feature System
22

3-
Every rule declares a `RULE_FEATURES` constant. This typed metadata drives preset generation, documentation badges, and rule categorization.
3+
Every rule declares a `RULE_FEATURES` constant. This typed metadata drives documentation badges and rule categorization in the rules index.
44

55
## Feature Flags
66

@@ -48,35 +48,40 @@ const RULE_FEATURES = ["EXP"]; // static-components: experimental detection
4848

4949
## How Features Drive Presets
5050

51-
Feature metadata is the source of truth for badges and categorization, but the preset files themselves are maintained manually. The `scripts/20-check-rules.ts` script (run via `nub run check:rules`) verifies config consistency—registered rules are accounted for, config keys are valid, and preset hierarchies hold—but it does not check `RULE_FEATURES` flags. Keeping `disable-type-checked` and `disable-experimental` aligned with `RULE_FEATURES` is currently a manual step.
51+
Feature metadata is the source of truth for badges and categorization, but the preset files themselves are maintained manually. The `scripts/20-check-rules.ts` script (run via `nub run check:rules`) verifies config consistency—registered rules are accounted for, config keys are valid, and preset hierarchies hold. It also checks that the feature badges in each rule's `.mdx` docs and the rules index match its `RULE_FEATURES`. What it does not check is the alignment between `RULE_FEATURES` and the `disable-type-checked` / `disable-experimental` presets; keeping those aligned is currently a manual step.
5252

5353
Rules marked `TSC` are disabled in `disable-type-checked.ts`:
5454

5555
```ts
5656
export const rules: Linter.RulesRecord = {
57-
"react-x/no-implicit-children": "off",
58-
"react-x/no-implicit-key": "off",
59-
"react-x/no-implicit-ref": "off",
60-
"react-x/no-leaked-conditional-rendering": "off",
61-
"react-x/no-unused-props": "off",
57+
"@eslint-react/no-implicit-children": "off",
58+
"@eslint-react/no-implicit-key": "off",
59+
"@eslint-react/no-implicit-ref": "off",
60+
"@eslint-react/no-leaked-conditional-rendering": "off",
61+
"@eslint-react/no-unused-props": "off",
6262
};
6363
```
6464

6565
Rules marked `EXP` are disabled in `disable-experimental.ts`:
6666

6767
```ts
6868
export const rules: Linter.RulesRecord = {
69-
"react-x/globals": "off",
70-
"react-x/immutability": "off",
71-
"react-x/no-duplicate-key": "off",
72-
"react-x/no-implicit-children": "off",
73-
"react-x/no-implicit-key": "off",
74-
"react-x/no-implicit-ref": "off",
75-
"react-x/no-misused-capture-owner-stack": "off",
76-
"react-x/no-unused-props": "off",
77-
"react-x/no-unused-state": "off",
78-
"react-x/refs": "off",
79-
"react-x/set-state-in-render": "off",
69+
"@eslint-react/globals": "off",
70+
"@eslint-react/immutability": "off",
71+
"@eslint-react/no-duplicate-key": "off",
72+
"@eslint-react/no-implicit-children": "off",
73+
"@eslint-react/no-implicit-key": "off",
74+
"@eslint-react/no-implicit-ref": "off",
75+
"@eslint-react/no-misused-capture-owner-stack": "off",
76+
"@eslint-react/no-unused-props": "off",
77+
"@eslint-react/no-unused-state": "off",
78+
"@eslint-react/refs": "off",
79+
"@eslint-react/set-state-in-render": "off",
80+
"@eslint-react/static-components": "off",
81+
82+
"@eslint-react/rsc-function-definition": "off",
83+
84+
"@eslint-react/web-api-no-leaked-fetch": "off",
8085
};
8186
```
8287

‎docs/rule-relations-table.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
| ------------------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
| `react-x/error-boundaries` | `react-x/no-class-component` | Disallows class components except for error boundaries |
88
| `react-x/exhaustive-deps` | `react-x/rules-of-hooks` | Enforces the Rules of Hooks |
9-
| `react-x/immutability` | `react-x/purity` | Validates against passing functions that mutate captured local variables into frozen contexts such as JSX props, hook arguments, and hook return values |
9+
| `react-x/immutability` | `react-x/purity` | Validates that components and hooks are pure by checking that they do not call known-impure functions during render |
1010
| `react-x/no-access-state-in-setstate` | `react-x/no-direct-mutation-state` | Disallows direct mutation of `this.state` |
1111
| `react-x/no-array-index-key` | `react-x/no-duplicate-key` | Prevents duplicate `key` props on sibling elements when rendering lists |
1212
| `react-x/no-array-index-key` | `react-x/no-implicit-key` | Prevents implicitly passing the `key` prop to components |
@@ -80,7 +80,7 @@
8080
| `react-x/no-unused-state` | `react-x/no-unused-props` | Warns about component props that are defined but never used |
8181
| `react-x/no-use-context` | `react-naming-convention/context-name` | Enforces identifier names assigned from `createContext` calls to be a valid component name with the suffix `Context` |
8282
| `react-x/no-use-context` | `react-x/no-context-provider` | Replaces usage of `<Context.Provider>` with `<Context>` |
83-
| `react-x/purity` | `react-x/immutability` | Validates that components and hooks are pure by checking that they do not call known-impure functions during render |
83+
| `react-x/purity` | `react-x/immutability` | Validates against passing functions that mutate captured local variables into frozen contexts such as JSX props, hook arguments, and hook return values |
8484
| `react-x/purity` | `react-x/rules-of-hooks` | Enforces the Rules of Hooks |
8585
| `react-x/purity` | `react-x/unsupported-syntax` | Validates against syntax that React Compiler does not support |
8686
| `react-x/refs` | `react-naming-convention/ref-name` | Enforces identifier names assigned from `useRef` calls to be either `ref` or end with `Ref` |
@@ -111,9 +111,9 @@
111111
| `react-dom/no-script-url` | `react-dom/no-dangerously-set-innerhtml` | Disallows DOM elements from using `dangerouslySetInnerHTML` |
112112
| `react-dom/no-script-url` | `react-dom/no-unsafe-target-blank` | Disallows `target="_blank"` without `rel="noreferrer noopener"` |
113113
| `react-dom/no-string-style-prop` | `react-dom/no-unknown-property` | Disallows unknown `DOM` properties |
114-
| `react-dom/no-string-style-prop` | `react-jsx/no-namespace` | Enforces the absence of a `namespace` in React elements |
115-
| `react-dom/no-unknown-property` | `react-dom/no-string-style-prop` | Disallows the use of string style prop in JSX |
116-
| `react-dom/no-unknown-property` | `react-jsx/no-namespace` | Enforces the absence of a `namespace` in React elements |
114+
| `react-dom/no-string-style-prop` | `react-jsx/no-namespace` | Disallow JSX namespace syntax, as React does not support them |
115+
| `react-dom/no-unknown-property` | `react-dom/no-string-style-prop` | Disallows the use of string style prop in JSX. Use an object instead. |
116+
| `react-dom/no-unknown-property` | `react-jsx/no-namespace` | Disallow JSX namespace syntax, as React does not support them |
117117
| `react-dom/no-unsafe-iframe-sandbox` | `react-dom/no-missing-iframe-sandbox` | Enforces an explicit `sandbox` attribute for `iframe` elements |
118118
| `react-dom/no-unsafe-iframe-sandbox` | `react-dom/no-unsafe-target-blank` | Disallows `target="_blank"` without `rel="noreferrer noopener"` |
119119
| `react-dom/no-unsafe-target-blank` | `react-dom/no-unsafe-iframe-sandbox` | Enforces that the `sandbox` attribute for `iframe` elements is not set to unsafe combinations |

‎docs/rule-rename-checklist.md‎

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ Checklist for renaming or moving rules in `eslint-plugin-react-x` and `@eslint-r
1717

1818
### A3. Test File
1919

20-
- [ ] Update the import path: `import rule, { RULE_NAME } from "./<new-name>/<new-name>";`
20+
- [ ] Update the import path: `import rule, { RULE_NAME } from "./<new-name>";`
2121

2222
### A4. Documentation
2323

2424
- [ ] Update front-matter `title`.
2525
- [ ] Update the `@eslint-react/<new-name>` and `react-x/<new-name>` full name code blocks.
26-
- [ ] Update **Implementation** section links.
26+
- [ ] Update **Resources** section links.
2727

2828
### A5. Plugin Registration (`src/plugin.ts`)
2929

@@ -73,14 +73,14 @@ Checklist for renaming or moving rules in `eslint-plugin-react-x` and `@eslint-r
7373

7474
- [ ] Create `src/rules/<rule-name>/<rule-name>.ts`:
7575
- Copy implementation from the source plugin.
76-
- Update `import { createRule } from "../utils"` to point to the react-x utils.
76+
- Update the createRule import to `import { createRule } from "@/utils/create-rule";`.
7777
- Add a fast-path skip guard if applicable:
7878
```ts
7979
if (!context.sourceCode.text.includes("<hookName>")) return {};
8080
```
8181
- [ ] Create `src/rules/<rule-name>/<rule-name>.spec.ts`:
8282
- Copy tests from the source plugin.
83-
- Update the import: `import rule, { RULE_NAME } from "./<rule-name>/<rule-name>";`.
83+
- Update the import: `import rule, { RULE_NAME } from "./<rule-name>";`.
8484
- [ ] Create `src/rules/<rule-name>/<rule-name>.mdx` following the template below.
8585
- [ ] Create `src/rules/<rule-name>/CHANGELOG.md` (copy from the source plugin or start fresh).
8686

@@ -122,23 +122,24 @@ Checklist for renaming or moving rules in `eslint-plugin-react-x` and `@eslint-r
122122
````mdx
123123
---
124124
title: <rule-name>
125+
description: One-line summary of what the rule enforces.
125126
---
126127

127-
**Full Name in [`@eslint-react/eslint-plugin`](https://npmx.dev/package/@eslint-react/eslint-plugin/v/latest)**
128+
**Full Name in [`eslint-plugin-react-x`](https://npmx.dev/package/eslint-plugin-react-x/v/latest)**
128129

129130
```plain copy
130-
@eslint-react/<rule-name>
131+
react-x/<rule-name>
131132
```
132133

133-
**Full Name in [`eslint-plugin-react-x`](https://npmx.dev/package/eslint-plugin-react-x/v/latest)**
134+
**Full Name in [`@eslint-react/eslint-plugin`](https://npmx.dev/package/@eslint-react/eslint-plugin/v/latest)**
134135

135136
```plain copy
136-
react-x/<rule-name>
137+
@eslint-react/<rule-name>
137138
```
138139

139140
**Features**
140141

141-
`⚙️` ← use `🧪` for experimental rules
142+
`⚙️` ← use `🔧` for fixable, `🔄` for codemod, `🧪` for experimental rules
142143

143144
**Presets**
144145

@@ -150,7 +151,7 @@ react-x/<rule-name>
150151
`strict-typescript`
151152
`strict-type-checked`
152153

153-
## Description
154+
## Rule Details
154155

155156
One-paragraph summary of what the rule enforces and why.
156157

@@ -164,31 +165,27 @@ Document each option with its name, effect, and default value.
164165

165166
## Examples
166167

167-
### Failing
168+
### Writing a new component
169+
170+
Name each scenario section after the case it covers. Annotate each `tsx` code block with `// 🔴 explanation` for the discouraged pattern and `// 🟢 explanation` for the recommended pattern.
168171

169172
```tsx
170173
// 🔴 explanation
171174
```
172175

173-
### Passing
174-
175176
```tsx
176177
// 🟢 explanation
177178
```
178179

179-
## Implementation
180+
## Resources
180181

181182
- [Rule Source](https://github.com/Rel1cx/eslint-react/tree/main/plugins/eslint-plugin-react-x/src/rules/<rule-name>/<rule-name>.ts)
182183
- [Test Source](https://github.com/Rel1cx/eslint-react/tree/main/plugins/eslint-plugin-react-x/src/rules/<rule-name>/<rule-name>.spec.ts)
184+
- [Rule Changelog](https://github.com/Rel1cx/eslint-react/tree/main/plugins/eslint-plugin-react-x/src/rules/<rule-name>/CHANGELOG.md)
183185

184186
## Further Reading
185187

186188
- [React Docs: relevant link]()
187-
188-
---
189-
190-
## See Also
191-
192-
- [`related-rule`](./related-rule)\
193-
One-line description.
194189
````
190+
191+
Do not add a `## See Also` section to the source `.mdx` file—it is generated automatically from `docs/rule-relations-table.md` when the docs are copied to the website (`scripts/12-update-website.ts`).

‎packages/eslint/docs/README.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,21 @@
99

1010
## Type Aliases
1111

12-
| Type Alias | Description |
13-
| ------------------------------------------------------ | ------------- |
14-
| [ReportFixFunction](type-aliases/ReportFixFunction.md) | - |
15-
| [RuleContext](type-aliases/RuleContext.md) | Rule context. |
16-
| [RuleFeature](type-aliases/RuleFeature.md) | Rule feature. |
17-
| [RuleListener](type-aliases/RuleListener.md) | - |
12+
| Type Alias | Description |
13+
| ------------------------------------------------------ | ----------------------------------- |
14+
| [ReportFixFunction](type-aliases/ReportFixFunction.md) | - |
15+
| [RuleContext](type-aliases/RuleContext.md) | Represents the ESLint rule context. |
16+
| [RuleFeature](type-aliases/RuleFeature.md) | Represents the feature of a rule. |
17+
| [RuleListener](type-aliases/RuleListener.md) | - |
1818

1919
## Variables
2020

21-
| Variable | Description |
22-
| ------------------------------------- | ----------- |
23-
| [createRule](variables/createRule.md) | - |
21+
| Variable | Description |
22+
| ------------------------------------- | -------------------------------------------------------------------------- |
23+
| [createRule](variables/createRule.md) | The rule creator that generates documentation URLs for ESLint React rules. |
2424

2525
## Functions
2626

27-
| Function | Description |
28-
| --------------------------- | ------------------------------------------------------------- |
29-
| [merge](functions/merge.md) | Merges multiple visitor objects into a single visitor object. |
27+
| Function | Description |
28+
| --------------------------- | ------------------------------------------------------------ |
29+
| [merge](functions/merge.md) | Merge multiple visitor objects into a single visitor object. |

‎packages/eslint/docs/functions/merge.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,20 @@
66
function merge(base: RuleListener, ...rest: RuleListener[]): RuleListener;
77
```
88

9-
Merges multiple visitor objects into a single visitor object.
9+
Merge multiple visitor objects into a single visitor object.
1010

1111
## Parameters
1212

13-
| Parameter | Type | Description |
14-
| --------- | --------------------------------------------------- | -------------------------------------------------- |
15-
| `base` | [`RuleListener`](../type-aliases/RuleListener.md) | Base visitor object (target of merge). |
16-
| ...`rest` | [`RuleListener`](../type-aliases/RuleListener.md)[] | Additional visitor objects to merge (one or more). |
13+
| Parameter | Type | Description |
14+
| --------- | --------------------------------------------------- | ------------------------------------------------------ |
15+
| `base` | [`RuleListener`](../type-aliases/RuleListener.md) | The base visitor object (target of merge). |
16+
| ...`rest` | [`RuleListener`](../type-aliases/RuleListener.md)[] | The additional visitor objects to merge (one or more). |
1717

1818
## Returns
1919

2020
[`RuleListener`](../type-aliases/RuleListener.md)
2121

22-
Merged visitor object.
22+
The merged visitor object.
2323

2424
## Example
2525

‎packages/eslint/docs/type-aliases/RuleContext.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
type RuleContext<MessageIds, Options> = tseslint.RuleContext<MessageIds, Options>;
77
```
88

9-
Rule context.
9+
Represents the ESLint rule context.
1010

1111
## Type Parameters
1212

‎packages/eslint/docs/type-aliases/RuleFeature.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
type RuleFeature = "CFG" | "DBG" | "FIX" | "MOD" | "TSC" | "EXP";
77
```
88

9-
Rule feature.
9+
Represents the feature of a rule.
1010

1111
## Since
1212

‎packages/eslint/docs/variables/createRule.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ const createRule: <Options, MessageIds>(
88
) => RuleModuleWithName<MessageIds, Options, unknown>;
99
```
1010

11+
The rule creator that generates documentation URLs for ESLint React rules.
12+
1113
## Type Parameters
1214

1315
| Type Parameter |

‎packages/eslint/src/types.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import type * as tseslint from "@typescript-eslint/utils/ts-eslint";
22

33
/**
4-
* Rule context.
4+
* Represents the ESLint rule context.
55
* @since 0.0.1
66
*/
77
export type RuleContext<
@@ -13,7 +13,7 @@ export type RuleContext<
1313
>;
1414

1515
/**
16-
* Rule feature.
16+
* Represents the feature of a rule.
1717
* @since 1.20.0
1818
*/
1919
export type RuleFeature =

0 commit comments

Comments
 (0)