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

crates/oxc_linter/src/rules/eslint/no_irregular_whitespace.rs

@@ -16,26 +16,29 @@ pub struct NoIrregularWhitespace;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallows the use of irregular whitespaces in the code.
+    /// Disallows the use of irregular whitespace characters in the code.
     ///
-    /// ### Why is this bad
-    /// The use of irregular whitespaces can hinder code readability and
-    /// create inconsistencies, making maintenance and collaboration more challenging.
+    /// ### Why is this bad?
+    ///
+    /// Irregular whitespace characters are invisible to most editors and can
+    /// cause unexpected behavior, making code harder to debug and maintain.
+    /// They can also cause issues with code formatting and parsing.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// function  invalidExample  (  ) {
-    ///     return  42;
+    /// // Contains irregular whitespace characters (invisible)
+    /// function example() {
+    ///   var foo = 'bar'; // irregular whitespace before 'bar'
     /// }
     /// ```
-    /// Examples of **incorrect** code for this rule:
+    ///
+    /// Examples of **correct** code for this rule:
     /// ```javascript
-    /// function invalidExample () {
-    ///     return 42;
+    /// function example() {
+    ///   var foo = 'bar'; // regular spaces only
     /// }
-    /// ```
     NoIrregularWhitespace,
     eslint,
     correctness

crates/oxc_linter/src/rules/eslint/no_void.rs

@@ -22,10 +22,10 @@ declare_oxc_lint!(
     ///
     /// Disallows the use of the `void` operator.
     ///
-    /// Why is this bad
+    /// ### Why is this bad?
     ///
-    /// The `void` operator is often used to get `undefined`,
-    /// but this is unnecessary because `undefined` can be used directly instead.
+    /// The `void` operator is often used to get `undefined`, but this is
+    /// unnecessary because `undefined` can be used directly instead.
     ///
     /// ### Examples
     ///

crates/oxc_linter/src/rules/jest/no_restricted_jest_methods.rs

@@ -39,6 +39,12 @@ declare_oxc_lint!(
     ///
     /// Restrict the use of specific `jest` and `vi` methods.
     ///
+    /// ### Why is this bad?
+    ///
+    /// Certain Jest methods may be deprecated, discouraged in specific
+    /// contexts, or incompatible with your testing environment. Restricting
+    /// them helps maintain consistent and reliable test practices.
+    ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:

crates/oxc_linter/src/rules/jest/prefer_expect_resolves.rs

@@ -24,19 +24,24 @@ pub struct PreferExpectResolves;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// When working with promises, there are two primary ways you can test the resolved
-    /// value:
+    /// Prefer `await expect(...).resolves` over `expect(await ...)` when testing
+    /// promises.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// When working with promises, there are two primary ways you can test the
+    /// resolved value:
     /// 1. use the `resolve` modifier on `expect`
     /// (`await expect(...).resolves.<matcher>` style)
     /// 2. `await` the promise and assert against its result
     /// (`expect(await ...).<matcher>` style)
     ///
-    /// While the second style is arguably less dependent on `jest`, if the promise
-    /// rejects it will be treated as a general error, resulting in less predictable
-    /// behaviour and output from `jest`.
+    /// While the second style is arguably less dependent on `jest`, if the
+    /// promise rejects it will be treated as a general error, resulting in less
+    /// predictable behaviour and output from `jest`.
     ///
-    /// Additionally, favoring the first style ensures consistency with its `rejects`
-    /// counterpart, as there is no way of "awaiting" a rejection.
+    /// Additionally, favoring the first style ensures consistency with its
+    /// `rejects` counterpart, as there is no way of "awaiting" a rejection.
     ///
     /// ### Examples
     ///

crates/oxc_linter/src/rules/jest/prefer_to_be.rs

@@ -41,13 +41,19 @@ pub struct PreferToBe;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// When asserting against primitive literals such as numbers and strings, the
-    /// equality matchers all operate the same, but read slightly differently in code.
+    /// Recommends using `toBe` matcher for primitive literals and specific
+    /// matchers for `null`, `undefined`, and `NaN`.
     ///
-    /// This rule recommends using the `toBe` matcher in these situations, as it forms
-    /// the most grammatically natural sentence. For `null`, `undefined`, and `NaN` this
-    /// rule recommends using their specific `toBe` matchers, as they give better error
-    /// messages as well.
+    /// ### Why is this bad?
+    ///
+    /// When asserting against primitive literals such as numbers and strings,
+    /// the equality matchers all operate the same, but read slightly
+    /// differently in code.
+    ///
+    /// This rule recommends using the `toBe` matcher in these situations, as
+    /// it forms the most grammatically natural sentence. For `null`,
+    /// `undefined`, and `NaN` this rule recommends using their specific `toBe`
+    /// matchers, as they give better error messages as well.
     ///
     /// ### Examples
     ///

crates/oxc_linter/src/rules/jest/require_top_level_describe.rs

@@ -48,6 +48,14 @@ impl Default for RequireTopLevelDescribe {
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Requires test cases and hooks to be inside a top-level `describe` block.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// Having tests and hooks organized within `describe` blocks provides better
+    /// structure and grouping for test suites. It makes test output more readable
+    /// and helps with test organization, especially in larger codebases.
+    ///
     /// This rule triggers a warning if a test case (`test` and `it`) or a hook
     /// (`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
     /// top-level `describe` block.

crates/oxc_linter/src/rules/jsx_a11y/alt_text.rs

@@ -102,32 +102,29 @@ declare_oxc_lint!(
     /// Enforce that all elements that require alternative text have meaningful
     /// information to relay back to the end user.
     ///
-    /// ### Why is this necessary?
+    /// ### Why is this bad?
     ///
     /// Alternative text is a critical component of accessibility for screen
-    /// reader users, enabling them to understand the content and function
-    /// of an element.
-    ///
-    /// ### What it checks
-    ///
-    /// This rule checks for alternative text on the following elements:
-    /// `<img>`, `<area>`, `<input type="image">`, and `<object>`.
-    ///
-    /// ### How to fix it
-    ///
-    /// Ensure that the `alt` attribute is present and contains meaningful
-    /// text that describes the element's content or purpose.
+    /// reader users, enabling them to understand the content and function of
+    /// an element. Missing or inadequate alt text makes content inaccessible
+    /// to users who rely on assistive technologies.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```jsx
-    /// <img src="flower.jpg" alt="A close-up of a white daisy" />
+    /// <img src="flower.jpg" />
+    /// <img src="flower.jpg" alt="" />
+    /// <object />
+    /// <area />
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```jsx
-    /// <img src="flower.jpg" />
+    /// <img src="flower.jpg" alt="A close-up of a white daisy" />
+    /// <img src="decorative.jpg" alt="" role="presentation" />
+    /// <object aria-label="Interactive chart" />
+    /// <area alt="Navigation link" />
     /// ```
     AltText,
     jsx_a11y,

crates/oxc_linter/src/rules/jsx_a11y/aria_unsupported_elements.rs

@@ -14,10 +14,15 @@ use crate::{
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Enforces that reserved DOM elements do not contain ARIA roles, states,
+    /// or properties.
+    ///
+    /// ### Why is this bad?
+    ///
     /// Certain reserved DOM elements do not support ARIA roles, states and
     /// properties. This is often because they are not visible, for example
-    /// `meta`, `html`, `script`, `style`. This rule enforces that these DOM
-    /// elements do not contain the `role` and/or `aria-*` props.
+    /// `meta`, `html`, `script`, `style`. Adding ARIA attributes to these
+    /// elements is meaningless and can create confusion for screen readers.
     ///
     /// ### Examples
     ///
@@ -28,7 +33,7 @@ declare_oxc_lint!(
     ///
     /// Examples of **correct** code for this rule:
     /// ```jsx
-    ///	<meta charset="UTF-8" />
+    /// <meta charset="UTF-8" />
     /// ```
     AriaUnsupportedElements,
     jsx_a11y,

crates/oxc_linter/src/rules/jsx_a11y/iframe_has_title.rs

@@ -29,12 +29,10 @@ declare_oxc_lint!(
     ///
     /// ### Why is this bad?
     ///
-    /// Screen reader users rely on a iframe title to describe the contents of the iframe.
-    /// Navigating through iframe and iframe elements quickly becomes difficult and confusing for users of this technology if the markup does not contain a title attribute.
-    ///
-    /// ### What it checks
-    ///
-    /// This rule checks for title property on iframe element.
+    /// Screen reader users rely on a iframe title to describe the contents of
+    /// the iframe. Navigating through iframe and iframe elements quickly
+    /// becomes difficult and confusing for users of this technology if the
+    /// markup does not contain a title attribute.
     ///
     /// ### Examples
     ///

crates/oxc_linter/src/rules/jsx_a11y/img_redundant_alt.rs

@@ -66,19 +66,15 @@ impl ImgRedundantAltConfig {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Enforce img alt attribute does not contain the word image, picture, or photo. Screenreaders already announce img elements as an image.
-    /// There is no need to use words such as image, photo, and/or picture.
+    /// Enforce that `img` alt attributes do not contain redundant words like
+    /// "image", "picture", or "photo".
     ///
-    /// ### Why is this necessary?
+    /// ### Why is this bad?
     ///
-    /// Alternative text is a critical component of accessibility for screen
-    /// reader users, enabling them to understand the content and function
-    /// of an element.
-    ///
-    /// ### What it checks
-    ///
-    /// This rule checks for alternative text on the following elements:
-    /// `<img>` and the components which you define in options.components with the exception of components which is hidden from screen reader.
+    /// Screen readers already announce `img` elements as an image, so there is
+    /// no need to use words such as "image", "photo", or "picture" in the alt
+    /// text. This creates redundant information for users of assistive
+    /// technologies and makes the alt text less concise and useful.
     ///
     /// ### Examples
     ///

crates/oxc_linter/src/rules/jsx_a11y/no_autofocus.rs

@@ -25,9 +25,14 @@ pub struct NoAutofocus {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Enforce that `autoFocus` prop is not used on elements. Autofocusing
-    /// elements can cause usability issues for sighted and non-sighted users,
-    /// alike.
+    /// Enforce that `autoFocus` prop is not used on elements.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// Autofocusing elements can cause usability issues for sighted and
+    /// non-sighted users alike. It can be disorienting when focus is shifted
+    /// without user input and can interfere with assistive technologies.
+    /// Users should control when and where focus moves on a page.
     ///
     /// ### Rule Option
     ///

crates/oxc_linter/src/rules/jsx_a11y/no_distracting_elements.rs

@@ -20,16 +20,12 @@ declare_oxc_lint!(
     ///
     /// Enforces that no distracting elements are used.
     ///
-    /// ### Why is this necessary?
+    /// ### Why is this bad?
     ///
     /// Elements that can be visually distracting can cause accessibility issues
-    /// with visually impaired users.  Such elements are most likely deprecated,
+    /// with visually impaired users. Such elements are most likely deprecated,
     /// and should be avoided. By default, `<marquee>` and `<blink>` elements
-    /// are visually distracting.
-    ///
-    /// ### What it checks
-    ///
-    /// This rule checks for marquee and blink element.
+    /// are visually distracting and can trigger vestibular disorders.
     ///
     /// ### Examples
     ///

crates/oxc_linter/src/rules/react/rules_of_hooks.rs

@@ -99,9 +99,60 @@ pub struct RulesOfHooks;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// This enforces the Rules of Hooks
+    /// Enforces the Rules of Hooks, ensuring that React Hooks are only called
+    /// in valid contexts and in the correct order.
     ///
-    /// <https://reactjs.org/docs/hooks-rules.html>
+    /// ### Why is this bad?
+    ///
+    /// React Hooks must follow specific rules to ensure they work correctly:
+    /// 1. Only call Hooks at the top level (never inside loops, conditions,
+    ///    or nested functions)
+    /// 2. Only call Hooks from React function components or custom Hooks
+    /// 3. Hooks must be called in the same order every time a component renders
+    ///
+    /// Breaking these rules can lead to bugs where state gets corrupted or
+    /// component behavior becomes unpredictable.
+    ///
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
+    /// // Don't call Hooks inside loops, conditions, or nested functions
+    /// function BadComponent() {
+    ///   if (condition) {
+    ///     const [state, setState] = useState(); // ❌ Hook in condition
+    ///   }
+    ///
+    ///   for (let i = 0; i < 10; i++) {
+    ///     useEffect(() => {}); // ❌ Hook in loop
+    ///   }
+    /// }
+    ///
+    /// // Don't call Hooks from regular JavaScript functions
+    /// function regularFunction() {
+    ///   const [state, setState] = useState(); // ❌ Hook in regular function
+    /// }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// // ✅ Call Hooks at the top level of a React component
+    /// function GoodComponent() {
+    ///   const [state, setState] = useState();
+    ///
+    ///   useEffect(() => {
+    ///     // Effect logic here
+    ///   });
+    ///
+    ///   return <div>{state}</div>;
+    /// }
+    ///
+    /// // ✅ Call Hooks from custom Hooks
+    /// function useCustomHook() {
+    ///   const [state, setState] = useState();
+    ///   return state;
+    /// }
+    /// ```
     ///
     RulesOfHooks,
     react,

crates/oxc_linter/src/rules/react/self_closing_comp.rs

@@ -34,11 +34,17 @@ impl Default for SelfClosingComp {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Detects components without children which can be self-closed to avoid unnecessary extra
-    /// closing tags.
+    /// Detects components without children which can be self-closed to avoid
+    /// unnecessary extra closing tags.
     ///
-    /// A self closing component which contains whitespace is allowed except when it also contains
-    /// a newline.
+    /// ### Why is this bad?
+    ///
+    /// Components without children don't need explicit closing tags. Using
+    /// self-closing syntax makes code more concise and reduces visual clutter.
+    /// It also follows common React and JSX conventions for empty elements.
+    ///
+    /// A self-closing component which contains whitespace is allowed except
+    /// when it also contains a newline.
     ///
     /// ### Examples
     ///