From 56fe5f8bb943c438d2989f97c790bee5ff36d93e Mon Sep 17 00:00:00 2001 From: Cameron Date: Thu, 5 Dec 2024 12:14:42 +0000 Subject: [PATCH] docs(linter): update rule documentation (#7680) part of #6050 --- .../src/rules/eslint/no_unreachable.rs | 21 +++++++++++++++++++ crates/oxc_linter/src/rules/eslint/no_void.rs | 14 +++++++++---- .../src/rules/jest/consistent_test_it.rs | 4 ++++ .../src/rules/jest/max_nested_describe.rs | 19 ++++++++++------- .../src/rules/jest/no_conditional_in_test.rs | 7 ++++++- .../src/rules/jest/no_duplicate_hooks.rs | 13 +++++++----- .../src/rules/jest/no_large_snapshots.rs | 13 ++++++++---- .../src/rules/jest/no_mocks_import.rs | 15 +++++++++++-- 8 files changed, 83 insertions(+), 23 deletions(-) diff --git a/crates/oxc_linter/src/rules/eslint/no_unreachable.rs b/crates/oxc_linter/src/rules/eslint/no_unreachable.rs index 0c23c911b..97d2b328a 100644 --- a/crates/oxc_linter/src/rules/eslint/no_unreachable.rs +++ b/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 ); diff --git a/crates/oxc_linter/src/rules/eslint/no_void.rs b/crates/oxc_linter/src/rules/eslint/no_void.rs index c475613fa..995aa223e 100644 --- a/crates/oxc_linter/src/rules/eslint/no_void.rs +++ b/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"; diff --git a/crates/oxc_linter/src/rules/jest/consistent_test_it.rs b/crates/oxc_linter/src/rules/jest/consistent_test_it.rs index 59d9fadd5..bf8e54a45 100644 --- a/crates/oxc_linter/src/rules/jest/consistent_test_it.rs +++ b/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 diff --git a/crates/oxc_linter/src/rules/jest/max_nested_describe.rs b/crates/oxc_linter/src/rules/jest/max_nested_describe.rs index ee2ec8c0f..5eb5dd957 100644 --- a/crates/oxc_linter/src/rules/jest/max_nested_describe.rs +++ b/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', () => { diff --git a/crates/oxc_linter/src/rules/jest/no_conditional_in_test.rs b/crates/oxc_linter/src/rules/jest/no_conditional_in_test.rs index 1e5754edc..1030320c3 100644 --- a/crates/oxc_linter/src/rules/jest/no_conditional_in_test.rs +++ b/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 /// diff --git a/crates/oxc_linter/src/rules/jest/no_duplicate_hooks.rs b/crates/oxc_linter/src/rules/jest/no_duplicate_hooks.rs index 89b0d2233..2e3b28f6d 100644 --- a/crates/oxc_linter/src/rules/jest/no_duplicate_hooks.rs +++ b/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 diff --git a/crates/oxc_linter/src/rules/jest/no_large_snapshots.rs b/crates/oxc_linter/src/rules/jest/no_large_snapshots.rs index 701bda242..84b5625f0 100644 --- a/crates/oxc_linter/src/rules/jest/no_large_snapshots.rs +++ b/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 diff --git a/crates/oxc_linter/src/rules/jest/no_mocks_import.rs b/crates/oxc_linter/src/rules/jest/no_mocks_import.rs index a95dee99c..11acf1281 100644 --- a/crates/oxc_linter/src/rules/jest/no_mocks_import.rs +++ b/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