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

part of #6050

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

@@ -25,6 +25,27 @@ declare_oxc_lint!(
     ///
     /// Disallow unreachable code after `return`, `throw`, `continue`, and `break` statements
     ///
+    /// ### Why is this bad?
+    ///
+    /// Unreachable code after a `return`, `throw`, `continue`, or `break` statement can never be run.
+    ///
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```ts
+    /// function foo() {
+    ///     return 2;
+    ///     console.log("this will never be executed");
+    /// }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```ts
+    /// function foo() {
+    ///     console.log("this will be executed");
+    ///     return 2;
+    /// }
+    /// ```
     NoUnreachable,
     nursery
 );

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

@@ -22,14 +22,20 @@ declare_oxc_lint!(
     ///
     /// Disallow `void` operators.
     ///
-    /// ### Example
+    /// Why is this bad
     ///
-    /// ```javascript
-    /// // error
+    /// The `void` operator is often used to obtain the `undefined` primitive value, but it is unnecessary. You can use `undefined` directly instead.
+    ///
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```ts
     /// void 0;
     /// var foo = void 0;
+    /// ```
     ///
-    /// // success
+    /// Examples of **correct** code for this rule:
+    /// ```ts
     /// "var foo = bar()";
     /// "foo.void()";
     /// "foo.void = bar";

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

@@ -101,6 +101,10 @@ declare_oxc_lint!(
     /// - **it:** `it`, `xit`, `fit`, `it.only`, `it.skip`.
     /// - **test:** `test`, `xtest`, `test.only`, `test.skip`.
     ///
+    /// ### Why is this bad?
+    ///
+    /// It's a good practice to be consistent in your test suite, so that all tests are written in the same way.
+    ///
     /// ### Example
     ///
     /// ```javascript

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

@@ -33,17 +33,20 @@ impl Default for MaxNestedDescribe {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// This rule enforces a maximum depth to nested `describe()` calls to improve code
-    /// clarity in your tests.
+    /// This rule enforces a maximum depth to nested `describe()` calls.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// Nesting `describe()` blocks too deeply can make the test suite hard to read and understand.
+    ///
+    ///
+    /// ### Example
     ///
     /// The following patterns are considered warnings (with the default option of
     /// `{ "max": 5 } `):
     ///
-    /// ### Example
-    ///
+    /// /// /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    ///
-    /// // invalid
     /// describe('foo', () => {
     ///     describe('bar', () => {
     ///         describe('baz', () => {
@@ -75,8 +78,10 @@ declare_oxc_lint!(
     ///         });
     ///     });
     /// });
+    /// ```
     ///
-    /// // valid
+    /// Examples of **correct** code for this rule:
+    /// ```ts
     /// describe('foo', () => {
     ///     describe('bar', () => {
     ///         it('should get something', () => {

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

@@ -18,7 +18,12 @@ pub struct NoConditionalInTest;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// This rule reports on any use of a conditional statement such as if, switch, and ternary expressions.
+    ///
+    /// Disallow conditional statements in tests.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// Conditional statements in tests can make the test harder to read and understand. It is better to have a single test case per test function.
     ///
     /// ### Examples
     ///

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

@@ -26,12 +26,16 @@ pub struct NoDuplicateHooks;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// A `describe` block should not contain duplicate hooks.
+    /// Disallows duplicate hooks in describe blocks.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// Having duplicate hooks in a describe block can lead to confusion and unexpected behavior.
     ///
     /// ### Example
-    /// ```javascript
     ///
-    /// // invalid
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
     /// describe('foo', () => {
     ///     beforeEach(() => {
     ///         // some setup
@@ -65,9 +69,8 @@ declare_oxc_lint!(
     /// });
     /// ```
     ///
+    /// Examples of **correct** code for this rule:
     /// ```javascript
-    ///
-    /// // valid
     /// describe('foo', () => {
     ///     beforeEach(() => {
     ///         // some setup

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

@@ -52,6 +52,10 @@ impl Deref for NoLargeSnapshots {
 declare_oxc_lint!(
     /// ### What it does
     ///
+    /// Disallow large snapshots.
+    ///
+    /// ### Why is this bad?
+    ///
     /// When using Jest's snapshot capability one should be mindful of the size of
     /// created snapshots. As a general best practice snapshots should be limited in
     /// size in order to be more manageable and reviewable. A stored snapshot is only as
@@ -60,9 +64,9 @@ declare_oxc_lint!(
     ///
     /// ### Example
     ///
-    /// ```javascript
     ///
-    /// // invalid
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
     /// exports[`a large snapshot 1`] = `
     /// line 1
     /// line 2
@@ -116,8 +120,9 @@ declare_oxc_lint!(
     /// line 50
     /// line 51
     /// `;
-    ///
-    /// // valid
+    /// ```
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
     /// exports[`a more manageable and readable snapshot 1`] = `
     /// line 1
     /// line 2

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

@@ -22,11 +22,22 @@ declare_oxc_lint!(
     ///
     /// This rule reports imports from a path containing a __mocks__ component.
     ///
+    /// ### Why is this bad?
+    ///
+    /// Manually importing mocks from a `__mocks__` directory can lead to unexpected behavior.
+    ///
     /// ### Example
-    /// ```javascript
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```ts
     /// import thing from './__mocks__/index';
     /// require('./__mocks__/index');
-    /// require('__mocks__');
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```ts
+    /// import thing from 'thing';
+    /// require('thing');
     /// ```
     NoMocksImport,
     style