docs(linter): update rule documentation (#7681)

part of #6050

crates/oxc_linter/src/rules/oxc/bad_min_max_func.rs

@@ -25,11 +25,26 @@ declare_oxc_lint!(
     /// Checks whether the clamp function `Math.min(Math.max(x, y), z)` always evaluate to a
     /// constant result because the arguments are in the wrong order.
     ///
+    /// ### Why is this bad?
+    ///
+    /// The `Math.min(Math.max(x, y), z)` function is used to clamp a value between two other values.
+    /// If the arguments are in the wrong order, the function will always evaluate to a constant result.
+    ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// Math.min(Math.max(100, x), 0);
     /// Math.max(1000, Math.min(0, z));
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    ///
+    /// ```javascript
+    /// Math.max(0, Math.min(100, x));
+    /// Math.min(0, Math.max(1000, z));
+    /// ```
+    ///
     BadMinMaxFunc,
     correctness
 );

crates/oxc_linter/src/rules/oxc/missing_throw.rs

@@ -19,11 +19,23 @@ declare_oxc_lint!(
     ///
     /// Checks whether the `throw` keyword is missing in front of a `new` expression.
     ///
+    /// ### Why is this bad?
+    ///
+    /// The `throw` keyword is required in front of a `new` expression to throw an error. Omitting it is usually a mistake.
+    ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// function foo() { throw Error() }
     /// const foo = () => { new Error() }
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// function foo() { throw new Error() }
+    /// const foo = () => { throw new Error() }
+    /// ```
     MissingThrow,
     correctness,
     suggestion

crates/oxc_linter/src/rules/oxc/number_arg_out_of_range.rs

@@ -28,12 +28,26 @@ declare_oxc_lint!(
     ///
     /// Checks whether the radix or precision arguments of number-related functions exceeds the limit.
     ///
+    /// ### Why is this bad?
+    ///
+    /// The radix argument of `Number.prototype.toString` should be between 2 and 36.
+    /// The precision argument of `Number.prototype.toFixed` and `Number.prototype.toExponential` should be between 0 and 20.
+    /// The precision argument of `Number.prototype.toPrecision` should be between 1 and 21.
+    ///
     /// ### Example
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// var x = 42;
     /// var s_radix_64 = x.toString(64);
     /// var s = x.toString(1);
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// var x = 42;
+    /// var s_radix_16 = x.toString(16);
+    /// ```
+    ///
     NumberArgOutOfRange,
     correctness
 );

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

@@ -59,10 +59,21 @@ declare_oxc_lint!(
     ///
     /// Enforce a consistent boolean attribute style in your code.
     ///
+    /// ### Why is this bad?
+    ///
+    /// In JSX, you can set a boolean attribute to `true` or omit it. This rule will enforce a consistent style for boolean attributes.
+    ///
     /// ### Example
+    /// Examples of **incorrect** code for this rule:
     /// ```jsx
     /// const Hello = <Hello personal={true} />;
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```jsx
+    /// const Hello = <Hello personal />;
+    /// ```
+    ///
     JsxBooleanValue,
     style,
     fix,

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

@@ -40,6 +40,10 @@ declare_oxc_lint!(
     ///
     /// Enforce `key` prop for elements in array
     ///
+    /// ### Why is this bad?
+    ///
+    /// React requires a `key` prop for elements in an array to help identify which items have changed, are added, or are removed.
+    ///
     /// ### Example
     ///
     /// Examples of **incorrect** code for this rule:

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

@@ -23,6 +23,10 @@ declare_oxc_lint!(
     ///
     /// This rule will warn you if you try to use the ReactDOM.render() return value.
     ///
+    /// ### Why is this bad?
+    ///
+    /// Using the return value from ReactDOM.render() is a legacy feature and should not be used.
+    ///
     /// ### Example
     ///
     /// Examples of **incorrect** code for this rule:

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

@@ -38,6 +38,10 @@ declare_oxc_lint!(
     ///
     /// This rule prevents using string literals in ref attributes.
     ///
+    /// ### Why is this bad?
+    ///
+    /// Using string literals in ref attributes is deprecated in React.
+    ///
     /// ### Example
     ///
     /// Examples of **incorrect** code for this rule:

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

@@ -25,6 +25,7 @@ pub struct PreferFunctionType;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Enforce using function types instead of interfaces with call signatures.
     /// TypeScript allows for two common ways to declare a type for a function:
     ///

crates/oxc_linter/src/rules/unicorn/consistent_empty_array_spread.rs

@@ -19,6 +19,10 @@ declare_oxc_lint!(
     /// When spreading a ternary in an array, we can use both [] and '' as fallbacks,
     /// but it's better to have consistent types in both branches.
     ///
+    /// ### Why is this bad?
+    ///
+    /// Having consistent types in both branches makes the code easier to read and understand.
+    ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:

crates/oxc_linter/src/rules/unicorn/prefer_node_protocol.rs

@@ -20,8 +20,12 @@ pub struct PreferNodeProtocol;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Prefer using the `node:protocol` when importing Node.js builtin modules
     ///
+    /// ### Why is this bad?
+    ///
+    /// Node.js builtin modules should be imported using the `node:` protocol to avoid ambiguity with local modules.
     ///
     /// ### Example
     ///

crates/oxc_linter/src/rules/unicorn/prefer_query_selector.rs

@@ -30,6 +30,11 @@ declare_oxc_lint!(
     ///
     /// Prefer `.querySelector()` over `.getElementById()`, `.querySelectorAll()` over `.getElementsByClassName()` and `.getElementsByTagName()`.
     ///
+    /// ### Why is this bad?
+    ///
+    /// - Using `.querySelector()` and `.querySelectorAll()` is more flexible and allows for more specific selectors.
+    /// - It's better to use the same method to query DOM elements. This helps keep consistency and it lends itself to future improvements (e.g. more specific selectors).
+    ///
     /// ### Example
     ///
     /// Examples of **incorrect** code for this rule:

crates/oxc_linter/src/rules/unicorn/text_encoding_identifier_case.rs

@@ -29,7 +29,14 @@ declare_oxc_lint!(
     /// Enforces `'utf8'` for UTF-8 encoding
     /// Enforces `'ascii'` for ASCII encoding.
     ///
+    /// ### Why is this bad?
+    ///
+    /// - Inconsistency in text encoding identifiers can make the code harder to read and understand.
+    /// - The ECMAScript specification does not define the case sensitivity of text encoding identifiers, but it is common practice to use lowercase.
+    ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// import fs from 'node:fs/promises';
     /// async function bad() {
@@ -39,7 +46,10 @@ declare_oxc_lint!(
     ///
     ///     const string = buffer.toString('utf-8');
     /// }
+    /// ```
     ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
     /// async function good() {
     ///     await fs.readFile(file, 'utf8');
     ///
@@ -47,7 +57,6 @@ declare_oxc_lint!(
     ///
     ///     const string = buffer.toString('utf8');
     /// }
-    ///
     /// ```
     TextEncodingIdentifierCase,
     style,