docs(linter): Complete linter rules documentation with missing "Why is this bad?" sections #12757

Copilot · 2025-08-02T12:56:51Z

This PR completes the documentation improvement initiative by adding missing "Why is this bad?" sections to linter rules and fixing formatting issues to align with the standardized documentation template.

Changes Made

Fixed Missing "Why is this bad?" Sections (16 rules total)

ESLint rules (2):

no_void: Added explanation about undefined being preferable to void operator
no_irregular_whitespace: Fixed header format and added explanation about invisible characters causing debugging issues

Jest rules (4):

no_restricted_jest_methods: Added explanation about maintaining consistent testing practices
prefer_expect_resolves: Restructured content with proper "Why is this bad?" header
prefer_to_be: Reorganized content to follow template format
require_top_level_describe: Added explanation about test organization benefits

JSX A11Y rules (6):

alt_text: Fixed incorrect examples (swapped correct/incorrect) and added proper "Why is this bad?" section
aria_unsupported_elements: Added explanation about meaningless ARIA on reserved elements
img_redundant_alt: Fixed header format and explained screen reader redundancy
no_autofocus: Added explanation about usability and accessibility concerns
no_distracting_elements: Fixed "Why is this necessary?" → "Why is this bad?" and improved content
iframe_has_title: Removed redundant "What it checks" section and improved formatting

React rules (2):

rules_of_hooks: Significantly expanded documentation with comprehensive examples and explanations
self_closing_comp: Added explanation about code conciseness and React conventions

TypeScript rules (1):

prefer_function_type: Restructured with proper template format and clearer examples

Unicorn rules (1):

prefer_math_min_max: Added proper "Why is this bad?" header with conciseness explanation

Documentation Improvements

Ensured all lines stay under 100 characters per project requirements
Fixed inconsistent header formats ("Why is this necessary?" → "Why is this bad?")
Removed redundant sections like "What it checks"
Improved example clarity and correctness
Maintained consistent indentation (2 spaces for code examples)
Added comprehensive explanations for complex rules like rules_of_hooks

Automated Validation

Created Python scripts to systematically find and validate documentation issues, ensuring complete coverage and consistency across all 541 linter rules.

Result

Before: 18 rules missing "Why is this bad?" sections
After: 0 rules remaining (100% completion)

All linter rules now have complete, properly formatted documentation following the established template format, improving developer experience and rule comprehension.

Fixes #6050.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

graphite-app · 2025-08-02T12:56:57Z

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

0-merge - adds this PR to the back of the merge queue
hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

codspeed-hq · 2025-08-02T13:20:44Z

CodSpeed Instrumentation Performance Report

Merging #12757 will not alter performance

_{Comparing copilot/fix-6050 (df626da) with main (1d910d5)}

Summary

✅ 34 untouched benchmarks

crates/oxc_linter/src/rules/typescript/prefer_function_type.rs

Boshen · 2025-08-02T13:28:36Z

@copilot find and fix by using the python script you wrote.

…ysis - Fixed "Why is this necessary?" → "Why is this bad?" in no_distracting_elements.rs - Removed redundant "What it checks" section in iframe_has_title.rs - Improved line length formatting and content clarity - Created Python validation scripts to automate finding and fixing documentation issues Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

Copilot · 2025-08-02T13:36:48Z

@copilot find and fix by using the python script you wrote.

Created Python validation scripts to find and fix the remaining documentation issues. Fixed the last 2 rules with formatting problems:

no_distracting_elements.rs - Changed "Why is this necessary?" → "Why is this bad?"
iframe_has_title.rs - Removed redundant "What it checks" section

All 541 linter rules now have proper documentation with the standardized template format. The scripts confirmed 100% completion of the documentation improvement task.

Commit: 3c7fb7d

## [1.10.0] - 2025-08-06 ### 🚀 Features - 44ac5a1 linter: Add eslint/no-unassigned-vars rule (#11365) (yefan) - ce6eeee linter: Add `eslint/prefer-destructuring` rule (#12721) (yefan) - 9b35600 linter/jsx-a11y: Add support for mapped attributes in label association checks (#12805) (camc314) - 5475075 vscode/language_server: Add `tsConfigPath` option (#12484) (Sysix) - a754f7a linter: Support `countVoidThis` option in `max-params` rule (#12604) (yefan) ### 🐛 Bug Fixes - 2c1dab6 linter/no-unassigned-vars: False positive with variables in for loop (#12833) (camc314) - 5a24574 linter/func-style: Fix more false positives (#12828) (camc314) - 33a7320 linter/no-throw-literal: Fix unconditional recursion in `could_be_error` (#12819) (camc314) - a3aec6a linter/explicit-module-boundary-types: Debug assertion fail with top level return (#12820) (camc314) - 6efe457 linter/no-empty-function: Respect allow options for functions and arrow functions (#12814) (camc314) - 1c21c46 linter/new-cap: Fix panic with computed member expr (#12804) (camc314) - 45206dd linter: Apply fix span offset after fixing the section source text (#12758) (Sysix) - 1e97e35 linter/unicorn/prefer-structured-clone: Update Default implementation for `PreferStructuredCloneConfig` (#12791) (camc314) - d382159 linter/unicorn/prefer-object-from-entries: Update Default implementation for `PreferObjectFromEntriesConfig` (#12790) (camc314) - b07d29c linter/typescript/no-this-alias: Update Default implementation for `NoThisAliasConfig` (#12789) (camc314) - 0db34ab linter/react/jsx-filename-case: Update Default implementation for `JsxFilenameExtensionConfig` (#12788) (camc314) - ff84eff linter/jest/prefer-lowercase-title: Update Default implementation for `PreferLowercaseTitleConfig` (#12787) (camc314) - 5175c6d linter/jest/no-large-snapshots: Update Default implementation for `NoLargeSnapshotsConfig` (#12786) (camc314) - 0eaebcd linter/jest/no-deprecated-functions: Update Default implementation for `JestConfig` (#12785) (camc314) - 4265db7 linter/import/no-anonymous-default-export: Update Default implementation for `NoAnonymousDefaultExport` config (#12784) (camc314) - 6a360e3 linter/import/extensions: Update Default implementation for ExtensionsConfig (#12783) (camc314) - 42c8f29 linter: Default options for `eslint/no-else-return` (#12762) (Sysix) - 4eac511 linter: Default options for `eslint/no-unneeded-ternary` (#12761) (Sysix) - 9c01dbf linter: Default options for `eslint/new-cap` (#12760) (Sysix) - b25406f linter/explicit-function-return-types: Update default values in ExplicitFunctionReturnTypeConfig (#12718) (camc314) - ce5876d parser: Validate inner expression of type assertions in assignment targets (#12614) (camc314) - 5383331 linter/explicit-mod-boundary-types: False positive with jsx elements (#12678) (camc314) - d0e99b5 linter/explicit-mod-boundary-types: False positive with call expressions (#12677) (camc314) - 525137e linter: Add missing options to no-inner-declarations (#12661) (camc314) - fc4a327 linter: No-unused-vars false positive with class property initializers (#12660) (camc314) - 6af8631 linter/no-unused-vars: False positive with chain expression (#12609) (camc314) - 744ef52 linter: Correct `array-type` handling of `default: 'array-simple'` (#12607) (yefan) ### 🚜 Refactor - 3f37ed1 linter: Replace `lazy_static` with `std::sync::LazyLock` (#12822) (Copilot) - 69fd08d semantic: Improve unused label tracking and add debug assertions (#12812) (camc314) - 030e397 linter: Simplify parsing CLI args (#12802) (overlookmotel) - c0e224a linter: Store `ExternalRuleId` in `OxlintOverrides` not raw names (#12502) (camc314) - 61587e4 linter: Correct comment (#12792) (overlookmotel) - 5adcb98 linter: Use `u32` to keep track of last fixed source text position (#12696) (Sysix) - 77acc11 linter, transformer: Use `Scoping::symbol_is_unused` (#12666) (overlookmotel) - ecf1cff language_server: Simplify offset adjustment by using `Message.move_offset` (#12647) (Sysix) - 7695393 linter: Simplify offset adjustment by using `Message.move_offset` (#12595) (Sysix) - b36dc92 linter: Refactor large arrays to reduce binary size (#12603) (Boshen) - 3b9f1f0 linter: Update iter_outer_expressions to take AstNodes reference (#12583) (camc314) ### 📚 Documentation - e760fd4 linter: Complete linter rules documentation with missing "Why is this bad?" sections (#12757) (Copilot) - 514322c rust: Add minimal documentation to example files in crates directory (#12731) (Copilot) - 1d910d5 linter: Fix typescript/consistent-type-imports rule options to match TypeScript ESLint (#12707) (Copilot) - 45e2fe8 rust: Fix typos and grammar mistakes in Rust documentation comments (#12715) (Copilot) - 7660a88 linter: Improve linter rule documentation with "Why is this bad?" sections and enhanced examples (#12711) (Copilot) - de1de35 rust: Add comprehensive README.md documentation for all Rust crates (#12706) (Copilot) ### ⚡ Performance - 09ae2a9 linter: Eliminate unnecessary Iterator::collect() allocations (#12776) (Copilot) - 693673b linter: Reduce iterations when collecting directories for nested configs (#12329) (overlookmotel) ### 🎨 Styling - cacbd1e linter/no-empty-function: Order match arms consistently (#12815) (camc314) - c15da81 codegen, formatter, linter, minifier, transformer: Re-order imports (#12725) (Copilot) ### 🧪 Testing - 3957fcc linter/no-undef: Add test case for `TSImportType` (#12800) (camc314) - d8ccff7 oxlint: Add `Tester::test_fix` mehod (#12754) (Sysix) - c6bfb8a linter: Add rule configuration consistency test (#12744) (camc314) - 2ceb835 linter: Fix offset for partical source texts (#12594) (Sysix) Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>

## [1.10.0] - 2025-08-06 ### 🚀 Features - 44ac5a1 linter: Add eslint/no-unassigned-vars rule (oxc-project#11365) (yefan) - ce6eeee linter: Add `eslint/prefer-destructuring` rule (oxc-project#12721) (yefan) - 9b35600 linter/jsx-a11y: Add support for mapped attributes in label association checks (oxc-project#12805) (camc314) - 5475075 vscode/language_server: Add `tsConfigPath` option (oxc-project#12484) (Sysix) - a754f7a linter: Support `countVoidThis` option in `max-params` rule (oxc-project#12604) (yefan) ### 🐛 Bug Fixes - 2c1dab6 linter/no-unassigned-vars: False positive with variables in for loop (oxc-project#12833) (camc314) - 5a24574 linter/func-style: Fix more false positives (oxc-project#12828) (camc314) - 33a7320 linter/no-throw-literal: Fix unconditional recursion in `could_be_error` (oxc-project#12819) (camc314) - a3aec6a linter/explicit-module-boundary-types: Debug assertion fail with top level return (oxc-project#12820) (camc314) - 6efe457 linter/no-empty-function: Respect allow options for functions and arrow functions (oxc-project#12814) (camc314) - 1c21c46 linter/new-cap: Fix panic with computed member expr (oxc-project#12804) (camc314) - 45206dd linter: Apply fix span offset after fixing the section source text (oxc-project#12758) (Sysix) - 1e97e35 linter/unicorn/prefer-structured-clone: Update Default implementation for `PreferStructuredCloneConfig` (oxc-project#12791) (camc314) - d382159 linter/unicorn/prefer-object-from-entries: Update Default implementation for `PreferObjectFromEntriesConfig` (oxc-project#12790) (camc314) - b07d29c linter/typescript/no-this-alias: Update Default implementation for `NoThisAliasConfig` (oxc-project#12789) (camc314) - 0db34ab linter/react/jsx-filename-case: Update Default implementation for `JsxFilenameExtensionConfig` (oxc-project#12788) (camc314) - ff84eff linter/jest/prefer-lowercase-title: Update Default implementation for `PreferLowercaseTitleConfig` (oxc-project#12787) (camc314) - 5175c6d linter/jest/no-large-snapshots: Update Default implementation for `NoLargeSnapshotsConfig` (oxc-project#12786) (camc314) - 0eaebcd linter/jest/no-deprecated-functions: Update Default implementation for `JestConfig` (oxc-project#12785) (camc314) - 4265db7 linter/import/no-anonymous-default-export: Update Default implementation for `NoAnonymousDefaultExport` config (oxc-project#12784) (camc314) - 6a360e3 linter/import/extensions: Update Default implementation for ExtensionsConfig (oxc-project#12783) (camc314) - 42c8f29 linter: Default options for `eslint/no-else-return` (oxc-project#12762) (Sysix) - 4eac511 linter: Default options for `eslint/no-unneeded-ternary` (oxc-project#12761) (Sysix) - 9c01dbf linter: Default options for `eslint/new-cap` (oxc-project#12760) (Sysix) - b25406f linter/explicit-function-return-types: Update default values in ExplicitFunctionReturnTypeConfig (oxc-project#12718) (camc314) - ce5876d parser: Validate inner expression of type assertions in assignment targets (oxc-project#12614) (camc314) - 5383331 linter/explicit-mod-boundary-types: False positive with jsx elements (oxc-project#12678) (camc314) - d0e99b5 linter/explicit-mod-boundary-types: False positive with call expressions (oxc-project#12677) (camc314) - 525137e linter: Add missing options to no-inner-declarations (oxc-project#12661) (camc314) - fc4a327 linter: No-unused-vars false positive with class property initializers (oxc-project#12660) (camc314) - 6af8631 linter/no-unused-vars: False positive with chain expression (oxc-project#12609) (camc314) - 744ef52 linter: Correct `array-type` handling of `default: 'array-simple'` (oxc-project#12607) (yefan) ### 🚜 Refactor - 3f37ed1 linter: Replace `lazy_static` with `std::sync::LazyLock` (oxc-project#12822) (Copilot) - 69fd08d semantic: Improve unused label tracking and add debug assertions (oxc-project#12812) (camc314) - 030e397 linter: Simplify parsing CLI args (oxc-project#12802) (overlookmotel) - c0e224a linter: Store `ExternalRuleId` in `OxlintOverrides` not raw names (oxc-project#12502) (camc314) - 61587e4 linter: Correct comment (oxc-project#12792) (overlookmotel) - 5adcb98 linter: Use `u32` to keep track of last fixed source text position (oxc-project#12696) (Sysix) - 77acc11 linter, transformer: Use `Scoping::symbol_is_unused` (oxc-project#12666) (overlookmotel) - ecf1cff language_server: Simplify offset adjustment by using `Message.move_offset` (oxc-project#12647) (Sysix) - 7695393 linter: Simplify offset adjustment by using `Message.move_offset` (oxc-project#12595) (Sysix) - b36dc92 linter: Refactor large arrays to reduce binary size (oxc-project#12603) (Boshen) - 3b9f1f0 linter: Update iter_outer_expressions to take AstNodes reference (oxc-project#12583) (camc314) ### 📚 Documentation - e760fd4 linter: Complete linter rules documentation with missing "Why is this bad?" sections (oxc-project#12757) (Copilot) - 514322c rust: Add minimal documentation to example files in crates directory (oxc-project#12731) (Copilot) - 1d910d5 linter: Fix typescript/consistent-type-imports rule options to match TypeScript ESLint (oxc-project#12707) (Copilot) - 45e2fe8 rust: Fix typos and grammar mistakes in Rust documentation comments (oxc-project#12715) (Copilot) - 7660a88 linter: Improve linter rule documentation with "Why is this bad?" sections and enhanced examples (oxc-project#12711) (Copilot) - de1de35 rust: Add comprehensive README.md documentation for all Rust crates (oxc-project#12706) (Copilot) ### ⚡ Performance - 09ae2a9 linter: Eliminate unnecessary Iterator::collect() allocations (oxc-project#12776) (Copilot) - 693673b linter: Reduce iterations when collecting directories for nested configs (oxc-project#12329) (overlookmotel) ### 🎨 Styling - cacbd1e linter/no-empty-function: Order match arms consistently (oxc-project#12815) (camc314) - c15da81 codegen, formatter, linter, minifier, transformer: Re-order imports (oxc-project#12725) (Copilot) ### 🧪 Testing - 3957fcc linter/no-undef: Add test case for `TSImportType` (oxc-project#12800) (camc314) - d8ccff7 oxlint: Add `Tester::test_fix` mehod (oxc-project#12754) (Sysix) - c6bfb8a linter: Add rule configuration consistency test (oxc-project#12744) (camc314) - 2ceb835 linter: Fix offset for partical source texts (oxc-project#12594) (Sysix) Co-authored-by: camc314 <18101008+camc314@users.noreply.github.com>

Initial plan

1afc870

Copilot AI assigned Copilot and Boshen Aug 2, 2025

Copilot started work on behalf of Boshen August 2, 2025 12:56 View session

Copilot AI and others added 2 commits August 2, 2025 13:10

Fix missing "Why is this bad?" sections for linter rules

fca5701

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

Complete majority of linter rule documentation improvements

5507ca3

Co-authored-by: Boshen <1430279+Boshen@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Improve linter rules documentation~~ Improve linter rules documentation with missing "Why is this bad?" sections Aug 2, 2025

Copilot finished work on behalf of Boshen August 2, 2025 13:13

Copilot AI requested a review from Boshen August 2, 2025 13:13

github-actions bot added the A-linter Area - Linter label Aug 2, 2025

Boshen marked this pull request as ready for review August 2, 2025 13:25

Boshen requested a review from camc314 as a code owner August 2, 2025 13:25

Boshen changed the title ~~Improve linter rules documentation with missing "Why is this bad?" sections~~ docs(linter): Improve linter rules documentation with missing "Why is this bad?" sections Aug 2, 2025

github-actions bot added the C-docs Category - Documentation. Related to user-facing or internal documentation label Aug 2, 2025

graphite-app bot reviewed Aug 2, 2025

View reviewed changes

crates/oxc_linter/src/rules/typescript/prefer_function_type.rs Outdated Show resolved Hide resolved

Copilot started work on behalf of Boshen August 2, 2025 13:28 View session

Copilot AI changed the title ~~docs(linter): Improve linter rules documentation with missing "Why is this bad?" sections~~ docs(linter): Complete linter rules documentation with missing "Why is this bad?" sections Aug 2, 2025

Copilot finished work on behalf of Boshen August 2, 2025 13:37

fix

df626da

Boshen merged commit e760fd4 into main Aug 2, 2025
24 checks passed

Boshen deleted the copilot/fix-6050 branch August 2, 2025 14:03

oxc-bot mentioned this pull request Aug 6, 2025

release(oxlint): v1.10.0 #12846

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs(linter): Complete linter rules documentation with missing "Why is this bad?" sections #12757

docs(linter): Complete linter rules documentation with missing "Why is this bad?" sections #12757

Uh oh!

Copilot AI commented Aug 2, 2025 •

edited

Loading

Uh oh!

graphite-app bot commented Aug 2, 2025

Uh oh!

codspeed-hq bot commented Aug 2, 2025 •

edited

Loading

Uh oh!

Uh oh!

Boshen commented Aug 2, 2025

Uh oh!

Copilot AI commented Aug 2, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

docs(linter): Complete linter rules documentation with missing "Why is this bad?" sections #12757

docs(linter): Complete linter rules documentation with missing "Why is this bad?" sections #12757

Uh oh!

Conversation

Copilot AI commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

Fixed Missing "Why is this bad?" Sections (16 rules total)

Documentation Improvements

Automated Validation

Result

Uh oh!

graphite-app bot commented Aug 2, 2025

How to use the Graphite Merge Queue

Uh oh!

codspeed-hq bot commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Instrumentation Performance Report

Merging #12757 will not alter performance

Summary

Uh oh!

Uh oh!

Boshen commented Aug 2, 2025

Uh oh!

Copilot AI commented Aug 2, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Aug 2, 2025 •

edited

Loading

codspeed-hq bot commented Aug 2, 2025 •

edited

Loading