From a540215c91d182590eb4f19cff8a50ff0794a5a1 Mon Sep 17 00:00:00 2001 From: dalaoshu Date: Fri, 6 Sep 2024 19:23:06 +0800 Subject: [PATCH] docs(linter): update docs `Examples` for linter rules (#5513) --- .../eslint/no_unused_private_class_members.rs | 14 +++++++----- crates/oxc_linter/src/rules/import/no_amd.rs | 12 +++++++--- .../src/rules/import/no_default_export.rs | 17 ++++++-------- .../src/rules/jsdoc/check_access.rs | 19 ++++++++++------ .../src/rules/jsdoc/check_property_names.rs | 16 +++++++++----- .../src/rules/jsdoc/check_tag_names.rs | 15 ++++++++----- .../oxc_linter/src/rules/jsdoc/empty_tags.rs | 19 ++++++++++------ .../src/rules/jsdoc/implements_on_classes.rs | 21 +++++++++++------- .../oxc_linter/src/rules/jsdoc/no_defaults.rs | 18 ++++++++++----- .../src/rules/jsdoc/require_param.rs | 15 ++++++++----- .../rules/jsdoc/require_param_description.rs | 15 ++++++++----- .../src/rules/jsdoc/require_param_name.rs | 15 ++++++++----- .../src/rules/jsdoc/require_param_type.rs | 15 ++++++++----- .../src/rules/jsdoc/require_property.rs | 21 ++++++++++++------ .../jsdoc/require_property_description.rs | 15 ++++++++----- .../src/rules/jsdoc/require_property_name.rs | 15 ++++++++----- .../src/rules/jsdoc/require_property_type.rs | 15 ++++++++----- .../src/rules/jsdoc/require_returns.rs | 18 ++++++++++----- .../jsdoc/require_returns_description.rs | 15 ++++++++----- .../src/rules/jsdoc/require_returns_type.rs | 15 ++++++++----- .../src/rules/jsdoc/require_yields.rs | 16 +++++++++----- crates/oxc_linter/src/rules/jsx_a11y/lang.rs | 16 +++++++------- .../src/rules/oxc/bad_char_at_comparison.rs | 9 +++++--- .../src/rules/oxc/bad_replace_all_arg.rs | 9 +++++--- .../src/rules/oxc/no_accumulating_spread.rs | 22 ++++++++++--------- .../src/rules/oxc/only_used_in_recursion.rs | 9 +++++--- .../consistent_indexed_object_style.rs | 15 ++++++------- .../src/rules/unicorn/catch_error_name.rs | 13 ++++++----- .../src/rules/unicorn/error_message.rs | 13 ++++++----- .../src/rules/unicorn/escape_case.rs | 12 +++++++--- .../rules/unicorn/explicit_length_check.rs | 17 +++++++++----- .../src/rules/unicorn/new_for_builtins.rs | 9 +++++--- .../unicorn/no_abusive_eslint_disable.rs | 11 +++++++--- .../src/rules/unicorn/no_document_cookie.rs | 9 +++++--- .../src/rules/unicorn/no_hex_escape.rs | 11 +++++++--- .../src/rules/unicorn/no_nested_ternary.rs | 11 +++++++--- .../src/rules/unicorn/no_new_array.rs | 9 +++++--- .../src/rules/unicorn/no_this_assignment.rs | 9 +++++--- .../src/rules/unicorn/no_typeof_undefined.rs | 9 +++++--- .../src/rules/unicorn/no_unreadable_iife.rs | 11 +++++++--- .../unicorn/no_useless_fallback_in_spread.rs | 10 +++++---- .../no_useless_promise_resolve_reject.rs | 9 +++++--- .../rules/unicorn/no_useless_switch_case.rs | 10 ++++++--- .../src/rules/unicorn/no_useless_undefined.rs | 12 ++++++---- .../src/rules/unicorn/number_literal_case.rs | 11 +++++++--- .../unicorn/prefer_add_event_listener.rs | 9 +++++--- .../src/rules/unicorn/prefer_code_point.rs | 9 +++++--- .../src/rules/unicorn/prefer_date_now.rs | 9 ++++---- .../rules/unicorn/prefer_dom_node_append.rs | 11 +++++----- .../rules/unicorn/prefer_dom_node_remove.rs | 9 +++++--- .../src/rules/unicorn/prefer_includes.rs | 10 +++++---- .../prefer_native_coercion_functions.rs | 9 +++++--- .../rules/unicorn/prefer_number_properties.rs | 9 +++++--- .../rules/unicorn/prefer_prototype_methods.rs | 10 ++++++--- .../src/rules/unicorn/prefer_set_size.rs | 10 +++++---- .../src/rules/unicorn/prefer_spread.rs | 12 ++++++---- ...require_number_to_fixed_digits_argument.rs | 15 ++++++++----- .../src/rules/unicorn/throw_new_error.rs | 10 +++++---- 58 files changed, 484 insertions(+), 265 deletions(-) diff --git a/crates/oxc_linter/src/rules/eslint/no_unused_private_class_members.rs b/crates/oxc_linter/src/rules/eslint/no_unused_private_class_members.rs index 239d4ad97d741..d25f3a09aad9e 100644 --- a/crates/oxc_linter/src/rules/eslint/no_unused_private_class_members.rs +++ b/crates/oxc_linter/src/rules/eslint/no_unused_private_class_members.rs @@ -24,10 +24,10 @@ declare_oxc_lint!( /// /// Private class members that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such class members take up space in the code and can lead to confusion by readers. /// - /// ### Example - /// ```javascript + /// ### Examples /// - /// /// bad + /// Examples of **incorrect** code for this rule: + /// ```javascript /// class A { /// #unusedMember = 5; /// } @@ -54,15 +54,17 @@ declare_oxc_lint!( /// get #unusedAccessor() {} /// set #unusedAccessor(value) {} /// } + /// ``` /// - /// /// Good + /// Examples of **correct** code for this rule: + /// ```javascript /// class A { /// #usedMember = 42; /// method() { /// return this.#usedMember; /// } /// } - + /// /// class B { /// #usedMethod() { /// return 42; @@ -71,7 +73,7 @@ declare_oxc_lint!( /// return this.#usedMethod(); /// } /// } - + /// /// class C { /// get #usedAccessor() {} /// set #usedAccessor(value) {} diff --git a/crates/oxc_linter/src/rules/import/no_amd.rs b/crates/oxc_linter/src/rules/import/no_amd.rs index 18318715c7873..2c5da588d825d 100644 --- a/crates/oxc_linter/src/rules/import/no_amd.rs +++ b/crates/oxc_linter/src/rules/import/no_amd.rs @@ -22,12 +22,18 @@ declare_oxc_lint!( /// /// Forbid AMD `require` and `define` calls. /// - /// ### Example + /// ### Why is this bad? + /// + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// /// ```javascript - /// // fail /// require([a, b], function() {} ); - /// // pass + /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript /// require('../name'); /// require(`../name`); /// ``` diff --git a/crates/oxc_linter/src/rules/import/no_default_export.rs b/crates/oxc_linter/src/rules/import/no_default_export.rs index d98d6b694d188..6bb8b4edeab8d 100644 --- a/crates/oxc_linter/src/rules/import/no_default_export.rs +++ b/crates/oxc_linter/src/rules/import/no_default_export.rs @@ -18,23 +18,20 @@ declare_oxc_lint!( /// /// ### Examples /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad1.js - /// - /// // There is a default export. - /// export const foo = 'foo'; - /// const bar = 'bar'; /// export default 'bar'; - /// ``` - /// - /// ```javascript - /// // bad2.js /// - /// // There is a default export. /// const foo = 'foo'; /// export { foo as default } /// ``` /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// export const foo = 'foo'; + /// export const bar = 'bar'; + /// ``` + /// NoDefaultExport, restriction ); diff --git a/crates/oxc_linter/src/rules/jsdoc/check_access.rs b/crates/oxc_linter/src/rules/jsdoc/check_access.rs index 07ec0c0d9b785..7d58e11855bb3 100644 --- a/crates/oxc_linter/src/rules/jsdoc/check_access.rs +++ b/crates/oxc_linter/src/rules/jsdoc/check_access.rs @@ -25,6 +25,7 @@ pub struct CheckAccess; declare_oxc_lint!( /// ### What it does + /// /// Checks that `@access` tags use one of the following values: /// - "package", "private", "protected", "public" /// @@ -33,20 +34,24 @@ declare_oxc_lint!( /// - Use of multiple instances of `@access` (or the `@public`, etc) on the same doc block. /// /// ### Why is this bad? - /// It is important to have a consistent way of specifying access levels. /// - /// ### Example - /// ```javascript - /// // Passing - /// /** @access private */ + /// It is important to have a consistent way of specifying access levels. /// - /// /** @private */ + /// ### Examples /// - /// // Failing + /// Examples of **incorrect** code for this rule: + /// ```javascript /// /** @access private @public */ /// /// /** @access invalidlevel */ /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @access private */ + /// + /// /** @private */ + /// ``` CheckAccess, restriction ); diff --git a/crates/oxc_linter/src/rules/jsdoc/check_property_names.rs b/crates/oxc_linter/src/rules/jsdoc/check_property_names.rs index 07e08ee78417e..8290f8e18d6d7 100644 --- a/crates/oxc_linter/src/rules/jsdoc/check_property_names.rs +++ b/crates/oxc_linter/src/rules/jsdoc/check_property_names.rs @@ -20,33 +20,39 @@ pub struct CheckPropertyNames; declare_oxc_lint!( /// ### What it does + /// /// Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots. /// /// ### Why is this bad? + /// /// `@property` tags with the same name can be confusing and may indicate a mistake. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing /// /** /// * @typedef {object} state /// * @property {number} foo + /// * @property {string} foo /// */ + /// /// /** /// * @typedef {object} state - /// * @property {object} foo /// * @property {number} foo.bar /// */ + /// ``` /// - /// // Failing + /// Examples of **correct** code for this rule: + /// ```javascript /// /** /// * @typedef {object} state /// * @property {number} foo - /// * @property {string} foo /// */ /// /// /** /// * @typedef {object} state + /// * @property {object} foo /// * @property {number} foo.bar /// */ /// ``` diff --git a/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs b/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs index 42e1865f359a3..a92d4fad1ce8a 100644 --- a/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs +++ b/crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs @@ -19,18 +19,18 @@ pub struct CheckTagNames(Box); declare_oxc_lint!( /// ### What it does + /// /// Reports invalid block tag names. /// Additionally checks for tag names that are redundant when using a type checker such as TypeScript. /// /// ### Why is this bad? + /// /// Using invalid tags can lead to confusion and make the documentation harder to read. /// - /// ### Example - /// ```javascript - /// // Passing - /// /** @param */ + /// ### Examples /// - /// // Failing + /// Examples of **incorrect** code for this rule: + /// ```javascript /// /** @Param */ /// /** @foo */ /// @@ -39,6 +39,11 @@ declare_oxc_lint!( /// * @type {string} /// */ /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @param */ + /// ``` CheckTagNames, correctness ); diff --git a/crates/oxc_linter/src/rules/jsdoc/empty_tags.rs b/crates/oxc_linter/src/rules/jsdoc/empty_tags.rs index 374820a5bdf2f..a814d02045dae 100644 --- a/crates/oxc_linter/src/rules/jsdoc/empty_tags.rs +++ b/crates/oxc_linter/src/rules/jsdoc/empty_tags.rs @@ -17,6 +17,7 @@ pub struct EmptyTags(Box); declare_oxc_lint!( /// ### What it does + /// /// Expects the following tags to be empty of any content: /// - `@abstract` /// - `@async` @@ -38,20 +39,24 @@ declare_oxc_lint!( /// - `@static` /// /// ### Why is this bad? - /// The void tags should be empty. /// - /// ### Example - /// ```javascript - /// // Passing - /// /** @async */ + /// The void tags should be empty. /// - /// /** @private */ + /// ### Examples /// - /// // Failing + /// Examples of **incorrect** code for this rule: + /// ```javascript /// /** @async foo */ /// /// /** @private bar */ /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @async */ + /// + /// /** @private */ + /// ``` EmptyTags, restriction ); diff --git a/crates/oxc_linter/src/rules/jsdoc/implements_on_classes.rs b/crates/oxc_linter/src/rules/jsdoc/implements_on_classes.rs index 0083b9a394685..91d769a408c90 100644 --- a/crates/oxc_linter/src/rules/jsdoc/implements_on_classes.rs +++ b/crates/oxc_linter/src/rules/jsdoc/implements_on_classes.rs @@ -22,15 +22,26 @@ pub struct ImplementsOnClasses; declare_oxc_lint!( /// ### What it does + /// /// Reports an issue with any non-constructor function using `@implements`. /// /// ### Why is this bad? + /// /// Constructor functions should be /// whether marked with `@class`, `@constructs`, or being an ES6 class constructor. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: + /// ```javascript + /// /** + /// * @implements {SomeClass} + /// */ + /// function quux () {} + /// ``` + /// + /// Examples of **correct** code for this rule: /// ```javascript - /// // Passing /// class Foo { /// /** /// * @implements {SomeClass} @@ -42,12 +53,6 @@ declare_oxc_lint!( /// * @class /// */ /// function quux () {} - /// - /// // Failing - /// /** - /// * @implements {SomeClass} - /// */ - /// function quux () {} /// ``` ImplementsOnClasses, correctness diff --git a/crates/oxc_linter/src/rules/jsdoc/no_defaults.rs b/crates/oxc_linter/src/rules/jsdoc/no_defaults.rs index 885cccfbd4bf6..c1e65618472c2 100644 --- a/crates/oxc_linter/src/rules/jsdoc/no_defaults.rs +++ b/crates/oxc_linter/src/rules/jsdoc/no_defaults.rs @@ -20,23 +20,29 @@ pub struct NoDefaults(Box); declare_oxc_lint!( /// ### What it does + /// /// This rule reports defaults being used on the relevant portion of `@param` or `@default`. /// It also optionally reports the presence of the square-bracketed optional arguments at all. /// /// ### Why is this bad? + /// /// The rule is intended to prevent the indication of defaults on tags /// where this would be redundant with ES6 default parameters. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** @param {number} foo */ + /// /** @param {number} [foo="7"] */ /// function quux (foo) {} - /// /** @param foo */ + /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @param {number} foo */ /// function quux (foo) {} /// - /// // Failing - /// /** @param {number} [foo="7"] */ + /// /** @param foo */ /// function quux (foo) {} /// ``` NoDefaults, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_param.rs b/crates/oxc_linter/src/rules/jsdoc/require_param.rs index 8d669be3e3b28..76f17aa91c2ae 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_param.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_param.rs @@ -23,20 +23,25 @@ pub struct RequireParam(Box); declare_oxc_lint!( /// ### What it does + /// /// Requires that all function parameters are documented with JSDoc `@param` tags. /// /// ### Why is this bad? + /// /// The rule is aimed at enforcing code quality and maintainability by requiring that all function parameters are documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing /// /** @param foo */ - /// function quux (foo) {} + /// function quux (foo, bar) {} + /// ``` /// - /// // Failing + /// Examples of **correct** code for this rule: + /// ```javascript /// /** @param foo */ - /// function quux (foo, bar) {} + /// function quux (foo) {} /// ``` RequireParam, pedantic, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_param_description.rs b/crates/oxc_linter/src/rules/jsdoc/require_param_description.rs index 85f43fb4d32ca..bbc3660802f1d 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_param_description.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_param_description.rs @@ -24,19 +24,24 @@ pub struct RequireParamDescription; declare_oxc_lint!( /// ### What it does + /// /// Requires that each `@param` tag has a description value. /// /// ### Why is this bad? + /// /// The description of a param should be documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** @param foo Foo. */ + /// /** @param foo */ /// function quux (foo) {} + /// ``` /// - /// // Failing - /// /** @param foo */ + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @param foo Foo. */ /// function quux (foo) {} /// ``` RequireParamDescription, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_param_name.rs b/crates/oxc_linter/src/rules/jsdoc/require_param_name.rs index e4a3116fa7f27..1e807a40a028b 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_param_name.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_param_name.rs @@ -21,19 +21,24 @@ pub struct RequireParamName; declare_oxc_lint!( /// ### What it does + /// /// Requires that all `@param` tags have names. /// /// ### Why is this bad? + /// /// The name of a param should be documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** @param {SomeType} foo */ + /// /** @param {SomeType} */ /// function quux (foo) {} + /// ``` /// - /// // Failing - /// /** @param {SomeType} */ + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @param {SomeType} foo */ /// function quux (foo) {} /// ``` RequireParamName, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_param_type.rs b/crates/oxc_linter/src/rules/jsdoc/require_param_type.rs index 67804881b0398..a464b5fb9c32f 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_param_type.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_param_type.rs @@ -24,19 +24,24 @@ pub struct RequireParamType; declare_oxc_lint!( /// ### What it does + /// /// Requires that each `@param` tag has a type value (within curly brackets). /// /// ### Why is this bad? + /// /// The type of a parameter should be documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** @param {SomeType} foo */ + /// /** @param foo */ /// function quux (foo) {} + /// ``` /// - /// // Failing - /// /** @param foo */ + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @param {SomeType} foo */ /// function quux (foo) {} /// ``` RequireParamType, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_property.rs b/crates/oxc_linter/src/rules/jsdoc/require_property.rs index 58b5cf588d204..709b4832f4c1d 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_property.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_property.rs @@ -21,30 +21,37 @@ pub struct RequireProperty; declare_oxc_lint!( /// ### What it does + /// /// Requires that all `@typedef` and `@namespace` tags have `@property` tags /// when their type is a plain `object`, `Object`, or `PlainObject`. /// /// ### Why is this bad? + /// /// Object type should have properties defined. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing /// /** /// * @typedef {Object} SomeTypedef - /// * @property {SomeType} propName Prop description /// */ + /// /// /** - /// * @typedef {object} Foo - /// * @property someProp + /// * @namespace {Object} SomeNamesoace /// */ + /// ``` /// - /// // Failing + /// Examples of **correct** code for this rule: + /// ```javascript /// /** /// * @typedef {Object} SomeTypedef + /// * @property {SomeType} propName Prop description /// */ + /// /// /** - /// * @namespace {Object} SomeNamesoace + /// * @typedef {object} Foo + /// * @property someProp /// */ /// ``` RequireProperty, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_property_description.rs b/crates/oxc_linter/src/rules/jsdoc/require_property_description.rs index 2c0987d662eb9..715561eed4322 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_property_description.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_property_description.rs @@ -19,23 +19,28 @@ pub struct RequirePropertyDescription; declare_oxc_lint!( /// ### What it does + /// /// Requires that all `@property` tags have descriptions. /// /// ### Why is this bad? + /// /// The description of a property should be documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing /// /** /// * @typedef {SomeType} SomeTypedef - /// * @property {number} foo Foo. + /// * @property {number} foo /// */ + /// ``` /// - /// // Failing + /// Examples of **correct** code for this rule: + /// ```javascript /// /** /// * @typedef {SomeType} SomeTypedef - /// * @property {number} foo + /// * @property {number} foo Foo. /// */ /// ``` RequirePropertyDescription, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_property_name.rs b/crates/oxc_linter/src/rules/jsdoc/require_property_name.rs index ac18791d79906..87ba362eb8ad7 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_property_name.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_property_name.rs @@ -19,23 +19,28 @@ pub struct RequirePropertyName; declare_oxc_lint!( /// ### What it does + /// /// Requires that all `@property` tags have names. /// /// ### Why is this bad? + /// /// The name of a property type should be documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing /// /** /// * @typedef {SomeType} SomeTypedef - /// * @property {number} foo + /// * @property {number} /// */ + /// ``` /// - /// // Failing + /// Examples of **correct** code for this rule: + /// ```javascript /// /** /// * @typedef {SomeType} SomeTypedef - /// * @property {number} + /// * @property {number} foo /// */ /// ``` RequirePropertyName, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_property_type.rs b/crates/oxc_linter/src/rules/jsdoc/require_property_type.rs index 9715cb8b1e62b..1ffb95a6a8d0b 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_property_type.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_property_type.rs @@ -19,23 +19,28 @@ pub struct RequirePropertyType; declare_oxc_lint!( /// ### What it does + /// /// Requires that each `@property` tag has a type value (within curly brackets). /// /// ### Why is this bad? + /// /// The type of a property should be documented. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing /// /** /// * @typedef {SomeType} SomeTypedef - /// * @property {number} foo + /// * @property foo /// */ + /// ``` /// - /// // Failing + /// Examples of **correct** code for this rule: + /// ```javascript /// /** /// * @typedef {SomeType} SomeTypedef - /// * @property foo + /// * @property {number} foo /// */ /// ``` RequirePropertyType, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_returns.rs b/crates/oxc_linter/src/rules/jsdoc/require_returns.rs index ec47f26547c77..dc38443871969 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_returns.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_returns.rs @@ -35,27 +35,33 @@ pub struct RequireReturns(Box); declare_oxc_lint!( /// ### What it does + /// /// Requires that return statements are documented. /// Will also report if multiple `@returns` tags are present. /// /// ### Why is this bad? + /// /// The rule is intended to prevent the omission of `@returns` tag when necessary. /// - /// ### Example - /// ```javascript - /// // Passing - /// /** @returns Foo. */ - /// function quux () { return foo; } + /// ### Examples /// - /// // Failing + /// Examples of **incorrect** code for this rule: + /// ```javascript /// /** Foo. */ /// function quux () { return foo; } + /// /// /** /// * @returns Foo! /// * @returns Foo? /// */ /// function quux () { return foo; } /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @returns Foo. */ + /// function quux () { return foo; } + /// ``` RequireReturns, pedantic, ); diff --git a/crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs b/crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs index 6a498f5f2459f..245aedf4e6a8c 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs @@ -21,20 +21,25 @@ pub struct RequireReturnsDescription; declare_oxc_lint!( /// ### What it does + /// /// Requires that the `@returns` tag has a description value. /// The error will not be reported if the return value is `void `or `undefined` or if it is `Promise` or `Promise`. /// /// ### Why is this bad? + /// /// A `@returns` tag should have a description value. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** @returns Foo. */ + /// /** @returns */ /// function quux (foo) {} + /// ``` /// - /// // Failing - /// /** @returns */ + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @returns Foo. */ /// function quux (foo) {} /// ``` RequireReturnsDescription, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs b/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs index f78c9a5cfce28..da0dc9ac65292 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_returns_type.rs @@ -21,19 +21,24 @@ pub struct RequireReturnsType; declare_oxc_lint!( /// ### What it does + /// /// Requires that `@returns` tag has a type value (in curly brackets). /// /// ### Why is this bad? + /// /// A `@returns` tag should have a type value. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** @returns {string} */ + /// /** @returns */ /// function quux (foo) {} + /// ``` /// - /// // Failing - /// /** @returns */ + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** @returns {string} */ /// function quux (foo) {} /// ``` RequireReturnsType, diff --git a/crates/oxc_linter/src/rules/jsdoc/require_yields.rs b/crates/oxc_linter/src/rules/jsdoc/require_yields.rs index f99187ccb8b3e..8a7bcc6dd8766 100644 --- a/crates/oxc_linter/src/rules/jsdoc/require_yields.rs +++ b/crates/oxc_linter/src/rules/jsdoc/require_yields.rs @@ -39,26 +39,32 @@ pub struct RequireYields(Box); declare_oxc_lint!( /// ### What it does + /// /// Requires that yields are documented. /// Will also report if multiple `@yields` tags are present. /// /// ### Why is this bad? + /// /// The rule is intended to prevent the omission of `@yields` tags when they are necessary. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Passing - /// /** * @yields Foo */ /// function * quux (foo) { yield foo; } /// - /// // Failing - /// function * quux (foo) { yield foo; } /// /** /// * @yields {undefined} /// * @yields {void} /// */ /// function * quux (foo) {} /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// /** * @yields Foo */ + /// function * quux (foo) { yield foo; } + /// ``` RequireYields, correctness ); diff --git a/crates/oxc_linter/src/rules/jsx_a11y/lang.rs b/crates/oxc_linter/src/rules/jsx_a11y/lang.rs index b9bd3406c89c3..0cf7d34f41cbf 100644 --- a/crates/oxc_linter/src/rules/jsx_a11y/lang.rs +++ b/crates/oxc_linter/src/rules/jsx_a11y/lang.rs @@ -36,20 +36,20 @@ declare_oxc_lint!( /// and access website in more than one language. /// /// - /// ### Example + /// ### Examples /// - /// // good - /// ```jsx - /// - /// - /// ``` - /// - /// // bad + /// Examples of **incorrect** code for this rule: /// ```jsx /// /// /// ```` /// + /// Examples of **correct** code for this rule: + /// ```jsx + /// + /// + /// ``` + /// /// ### Resources /// - [eslint-plugin-jsx-a11y/lang](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/main/docs/rules/lang.md) /// - [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) diff --git a/crates/oxc_linter/src/rules/oxc/bad_char_at_comparison.rs b/crates/oxc_linter/src/rules/oxc/bad_char_at_comparison.rs index 694e28d0248fb..4427c10645c71 100644 --- a/crates/oxc_linter/src/rules/oxc/bad_char_at_comparison.rs +++ b/crates/oxc_linter/src/rules/oxc/bad_char_at_comparison.rs @@ -31,13 +31,16 @@ declare_oxc_lint!( /// /// The `charAt` method returns a string of length 1. If the return value is compared with a string of length greater than 1, the comparison will always be false. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Bad: The return value of the `charAt` method is compared with a string of length greater than 1. /// a.charAt(4) === 'a2'; /// a.charAt(4) === '/n'; + /// ``` /// - /// // Good: The return value of the `charAt` method is compared with a string of length 1. + /// Examples of **correct** code for this rule: + /// ```javascript /// a.charAt(4) === 'a' /// a.charAt(4) === '\n'; /// ``` diff --git a/crates/oxc_linter/src/rules/oxc/bad_replace_all_arg.rs b/crates/oxc_linter/src/rules/oxc/bad_replace_all_arg.rs index 99ab0edc7de05..10551620c86b2 100644 --- a/crates/oxc_linter/src/rules/oxc/bad_replace_all_arg.rs +++ b/crates/oxc_linter/src/rules/oxc/bad_replace_all_arg.rs @@ -34,12 +34,15 @@ declare_oxc_lint!( /// /// The `replaceAll` method replaces all occurrences of a string with another string. If the global flag (g) is not used in the regular expression, only the first occurrence of the string will be replaced. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Bad: The global flag (g) is missing in the regular expression. /// withSpaces.replaceAll(/\s+/, ','); + /// ``` /// - /// // Good: The global flag (g) is used in the regular expression. + /// Examples of **correct** code for this rule: + /// ```javascript /// withSpaces.replaceAll(/\s+/g, ','); /// ``` BadReplaceAllArg, diff --git a/crates/oxc_linter/src/rules/oxc/no_accumulating_spread.rs b/crates/oxc_linter/src/rules/oxc/no_accumulating_spread.rs index 0e8525cace8dc..0e38524104fbe 100644 --- a/crates/oxc_linter/src/rules/oxc/no_accumulating_spread.rs +++ b/crates/oxc_linter/src/rules/oxc/no_accumulating_spread.rs @@ -76,9 +76,11 @@ pub struct NoAccumulatingSpread; declare_oxc_lint!( /// ### What it does + /// /// Prevents using object or array spreads on accumulators in `Array.prototype.reduce()` and in loops. /// /// ### Why is this bad? + /// /// Object and array spreads create a new object or array on each iteration. /// In the worst case, they also cause O(n) copies (both memory and time complexity). /// When used on an accumulator, this can lead to `O(n^2)` memory complexity and @@ -87,9 +89,17 @@ declare_oxc_lint!( /// For a more in-depth explanation, see this [blog post](https://prateeksurana.me/blog/why-using-object-spread-with-reduce-bad-idea/) /// by Prateek Surana. /// + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: + /// ```javascript + /// arr.reduce((acc, x) => ({ ...acc, [x]: fn(x) }), {}) + /// Object.keys(obj).reduce((acc, el) => ({ ...acc, [el]: fn(el) }), {}) + /// + /// let foo = []; for (let i = 0; i < 10; i++) { foo = [...foo, i]; } + /// ``` /// - /// ### Example - /// Pass + /// Examples of **correct** code for this rule: /// ```javascript /// function fn (x) { /// // ... @@ -108,14 +118,6 @@ declare_oxc_lint!( /// /// let foo = []; for (let i = 0; i < 10; i++) { foo.push(i); } /// ``` - /// - /// Fail - /// ```javascript - /// arr.reduce((acc, x) => ({ ...acc, [x]: fn(x) }), {}) - /// Object.keys(obj).reduce((acc, el) => ({ ...acc, [el]: fn(el) }), {}) - /// - /// let foo = []; for (let i = 0; i < 10; i++) { foo = [...foo, i]; } - /// ``` NoAccumulatingSpread, perf, ); diff --git a/crates/oxc_linter/src/rules/oxc/only_used_in_recursion.rs b/crates/oxc_linter/src/rules/oxc/only_used_in_recursion.rs index 6a181e73d70da..3067060285029 100644 --- a/crates/oxc_linter/src/rules/oxc/only_used_in_recursion.rs +++ b/crates/oxc_linter/src/rules/oxc/only_used_in_recursion.rs @@ -36,9 +36,10 @@ declare_oxc_lint!( /// /// It increase cognitive complexity and may impact performance. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```ts - /// // Bad - the argument `b` is only used in recursive calls /// function f(a: number, b: number): number { /// if (a == 0) { /// return 1 @@ -46,8 +47,10 @@ declare_oxc_lint!( /// return f(a - 1, b + 1) /// } /// } + /// ``` /// - /// // Good - the argument `b` is omitted + /// Examples of **correct** code for this rule: + /// ```ts /// function f(a: number): number { /// if (a == 0) { /// return 1 diff --git a/crates/oxc_linter/src/rules/typescript/consistent_indexed_object_style.rs b/crates/oxc_linter/src/rules/typescript/consistent_indexed_object_style.rs index aae2c657e5e1d..21de5b2389df6 100644 --- a/crates/oxc_linter/src/rules/typescript/consistent_indexed_object_style.rs +++ b/crates/oxc_linter/src/rules/typescript/consistent_indexed_object_style.rs @@ -28,28 +28,27 @@ enum ConsistentIndexedObjectStyleConfig { declare_oxc_lint!( /// ### What it does + /// /// Require or disallow the `Record` type. /// /// ### Why is this bad? + /// /// Inconsistent style for indexed object types can harm readability in a project. /// - /// ### Example - /// With "record": + /// ### Examples /// + /// Examples of **incorrect** code for this rule: /// ```ts - /// // bad /// interface Foo { /// [key: string]: unknown; - ///} + /// } /// type Foo = { /// [key: string]: unknown; - ///}; + /// }; /// ``` /// - /// With "index-signature": - /// + /// Examples of **correct** code for this rule: /// ```ts - /// // bad /// type Foo = Record; /// ``` ConsistentIndexedObjectStyle, diff --git a/crates/oxc_linter/src/rules/unicorn/catch_error_name.rs b/crates/oxc_linter/src/rules/unicorn/catch_error_name.rs index 103ee20298169..52971ada451dc 100644 --- a/crates/oxc_linter/src/rules/unicorn/catch_error_name.rs +++ b/crates/oxc_linter/src/rules/unicorn/catch_error_name.rs @@ -42,15 +42,18 @@ declare_oxc_lint!( /// /// This rule enforces naming conventions for catch statements. /// - /// ### Example - /// ```javascript + /// ### Why is this bad? + /// + /// ### Examples /// - /// // fail + /// Examples of **incorrect** code for this rule: + /// ```javascript /// try { } catch (foo) { } + /// ``` /// - /// // pass + /// Examples of **correct** code for this rule: + /// ```javascript /// try { } catch (error) { } - /// /// ``` CatchErrorName, style diff --git a/crates/oxc_linter/src/rules/unicorn/error_message.rs b/crates/oxc_linter/src/rules/unicorn/error_message.rs index 25dbcae6075f8..d71af0cfd1fd4 100644 --- a/crates/oxc_linter/src/rules/unicorn/error_message.rs +++ b/crates/oxc_linter/src/rules/unicorn/error_message.rs @@ -28,17 +28,20 @@ declare_oxc_lint!( /// /// This rule enforces a `message` value to be passed in when creating an instance of a built-in `Error` object, which leads to more readable and debuggable code. /// - /// ### Example + /// ### Why is this bad? + /// + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// throw Error() /// throw new TypeError() + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// throw new Error('Unexpected token') /// throw new TypeError('Number expected') - /// - /// /// ``` ErrorMessage, style diff --git a/crates/oxc_linter/src/rules/unicorn/escape_case.rs b/crates/oxc_linter/src/rules/unicorn/escape_case.rs index 89932557b9d69..4ddad1a9c4747 100644 --- a/crates/oxc_linter/src/rules/unicorn/escape_case.rs +++ b/crates/oxc_linter/src/rules/unicorn/escape_case.rs @@ -23,14 +23,20 @@ declare_oxc_lint!( /// /// Enforces defining escape sequence values with uppercase characters rather than lowercase ones. This promotes readability by making the escaped value more distinguishable from the identifier. /// - /// ### Example + /// ### Why is this bad? + /// + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // fail /// const foo = '\xa9'; /// const foo = '\ud834'; /// const foo = '\u{1d306}'; /// const foo = '\ca'; - /// // pass + /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript /// const foo = '\xA9'; /// const foo = '\uD834'; /// const foo = '\u{1D306}'; diff --git a/crates/oxc_linter/src/rules/unicorn/explicit_length_check.rs b/crates/oxc_linter/src/rules/unicorn/explicit_length_check.rs index 2d0ae5f31c992..017bf8ac9dded 100644 --- a/crates/oxc_linter/src/rules/unicorn/explicit_length_check.rs +++ b/crates/oxc_linter/src/rules/unicorn/explicit_length_check.rs @@ -61,19 +61,26 @@ declare_oxc_lint!( /// Enforces non-zero to be checked with: foo.length > 0 /// not-equal /// Enforces non-zero to be checked with: foo.length !== 0 - /// ### Example + /// + /// ### Why is this bad? + /// + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // fail - /// const isEmpty = !foo.length; /// const isEmpty = foo.length == 0; /// const isEmpty = foo.length < 1; /// const isEmpty = 0 === foo.length; /// const isEmpty = 0 == foo.length; /// const isEmpty = 1 > foo.length; - /// // Negative style is disallowed too + /// + /// const isEmpty = !foo.length; /// const isEmpty = !(foo.length > 0); /// const isEmptySet = !foo.size; - /// // pass + /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript /// const isEmpty = foo.length === 0; /// ``` ExplicitLengthCheck, diff --git a/crates/oxc_linter/src/rules/unicorn/new_for_builtins.rs b/crates/oxc_linter/src/rules/unicorn/new_for_builtins.rs index 1175915e36f42..e0d9683fd7d63 100644 --- a/crates/oxc_linter/src/rules/unicorn/new_for_builtins.rs +++ b/crates/oxc_linter/src/rules/unicorn/new_for_builtins.rs @@ -35,13 +35,16 @@ declare_oxc_lint!( /// They work the same, but `new` should be preferred for consistency with other constructors. /// /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const foo = new String('hello world'); /// const bar = Array(1, 2, 3); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// const foo = String('hello world'); /// const bar = new Array(1, 2, 3); /// ``` diff --git a/crates/oxc_linter/src/rules/unicorn/no_abusive_eslint_disable.rs b/crates/oxc_linter/src/rules/unicorn/no_abusive_eslint_disable.rs index e2f6849934da3..eed4973266ef5 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_abusive_eslint_disable.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_abusive_eslint_disable.rs @@ -17,14 +17,17 @@ pub struct NoAbusiveEslintDisable; declare_oxc_lint!( /// ### What it does + /// /// This rule disallows `eslint-disable` comments that do not specify any rules to disable. /// /// ### Why is this bad? + /// /// When only one rule should be disabled but the `eslint-disable` comment does not specify any rules, other useful errors will also be silently ignored. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// /* eslint-disable */ /// console.log(message); /// @@ -32,8 +35,10 @@ declare_oxc_lint!( /// /// // eslint-disable-next-line /// console.log(message); + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// /* eslint-disable no-console */ /// console.log(message); /// diff --git a/crates/oxc_linter/src/rules/unicorn/no_document_cookie.rs b/crates/oxc_linter/src/rules/unicorn/no_document_cookie.rs index bf21cb429cfd9..6dc12930dff83 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_document_cookie.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_document_cookie.rs @@ -35,17 +35,20 @@ declare_oxc_lint!( /// API](https://developer.mozilla.org/en-US/docs/Web/API/Cookie_Store_API) /// or a [cookie library](https://www.npmjs.com/search?q=cookie). /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// document.cookie = /// 'foo=bar' + /// '; Path=/' + /// '; Domain=example.com' + /// '; expires=Fri, 31 Dec 9999 23:59:59 GMT' + /// '; Secure'; + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// async function storeCookies() { /// await cookieStore.set({ /// name: 'foo', diff --git a/crates/oxc_linter/src/rules/unicorn/no_hex_escape.rs b/crates/oxc_linter/src/rules/unicorn/no_hex_escape.rs index 1531b9e59f70e..9f7449aa0727e 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_hex_escape.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_hex_escape.rs @@ -20,13 +20,18 @@ declare_oxc_lint!( /// /// Enforces a convention of using [Unicode escapes](https://mathiasbynens.be/notes/javascript-escapes#unicode) instead of [hexadecimal escapes](https://mathiasbynens.be/notes/javascript-escapes#hexadecimal) for consistency and clarity. /// - /// ### Example + /// ### Why is this bad? + /// + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // fail /// const foo = '\x1B'; /// const foo = `\x1B${bar}`; + /// ``` /// - /// // pass + /// Examples of **correct** code for this rule: + /// ```javascript /// const foo = '\u001B'; /// const foo = `\u001B${bar}`; /// ``` diff --git a/crates/oxc_linter/src/rules/unicorn/no_nested_ternary.rs b/crates/oxc_linter/src/rules/unicorn/no_nested_ternary.rs index d4af6ae4705e1..737ffff6f5366 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_nested_ternary.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_nested_ternary.rs @@ -22,19 +22,24 @@ pub struct NoNestedTernary; declare_oxc_lint!( /// ### What it does + /// /// This rule disallows deeply nested ternary expressions. /// Nested ternary expressions that are only one level deep and wrapped in parentheses are allowed. /// /// ### Why is this bad? + /// /// Nesting ternary expressions can make code more difficult to understand. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// const foo = i > 5 ? i < 100 ? true : false : true; /// const foo = i > 5 ? true : (i < 100 ? true : (i < 1000 ? true : false)); + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// const foo = i > 5 ? (i < 100 ? true : false) : true; /// const foo = i > 5 ? (i < 100 ? true : false) : (i < 100 ? true : false); /// ``` diff --git a/crates/oxc_linter/src/rules/unicorn/no_new_array.rs b/crates/oxc_linter/src/rules/unicorn/no_new_array.rs index 9b12f87927dbe..fef71df4c35fa 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_new_array.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_new_array.rs @@ -21,14 +21,17 @@ declare_oxc_lint!( /// /// When using the `Array` constructor with one argument, it's not clear whether the argument is meant to be the length of the array or the only element. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const array = new Array(1); /// const array = new Array(42); /// const array = new Array(foo); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// const array = Array.from({ length: 42 }); /// const array = [42]; /// ``` diff --git a/crates/oxc_linter/src/rules/unicorn/no_this_assignment.rs b/crates/oxc_linter/src/rules/unicorn/no_this_assignment.rs index 2875e47023f25..fd934822f68cb 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_this_assignment.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_this_assignment.rs @@ -26,9 +26,10 @@ declare_oxc_lint!( /// /// Assigning `this` to a variable is unnecessary and confusing. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // fail /// const foo = this; /// class Bar { /// method() { @@ -37,8 +38,10 @@ declare_oxc_lint!( /// } /// /// new Bar().method(); + /// ``` /// - /// // pass + /// Examples of **correct** code for this rule: + /// ```javascript /// class Bar { /// constructor(fooInstance) { /// this.fooInstance = fooInstance; diff --git a/crates/oxc_linter/src/rules/unicorn/no_typeof_undefined.rs b/crates/oxc_linter/src/rules/unicorn/no_typeof_undefined.rs index 74b9ccdd2caa7..b4aa5a61e97fb 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_typeof_undefined.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_typeof_undefined.rs @@ -26,12 +26,15 @@ declare_oxc_lint!( /// Checking if a value is `undefined` by using `typeof value === 'undefined'` is needlessly verbose. It's generally better to compare against `undefined` directly. The only time `typeof` is needed is when a global variable potentially does not exists, in which case, using `globalThis.value === undefined` may be better. /// /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// typeof foo === 'undefined'; + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// foo === undefined; /// ``` NoTypeofUndefined, diff --git a/crates/oxc_linter/src/rules/unicorn/no_unreadable_iife.rs b/crates/oxc_linter/src/rules/unicorn/no_unreadable_iife.rs index c5648fc822dca..3e85318960151 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_unreadable_iife.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_unreadable_iife.rs @@ -19,19 +19,24 @@ pub struct NoUnreadableIife; declare_oxc_lint!( /// ### What it does + /// /// This rule disallows IIFEs with a parenthesized arrow function body. /// /// ### Why is this bad? + /// /// IIFEs with a parenthesized arrow function body are unreadable. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// const foo = (bar => (bar ? bar.baz : baz))(getBar()); /// /// const foo = ((bar, baz) => ({bar, baz}))(bar, baz); + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// const bar = getBar(); /// const foo = bar ? bar.baz : baz; /// diff --git a/crates/oxc_linter/src/rules/unicorn/no_useless_fallback_in_spread.rs b/crates/oxc_linter/src/rules/unicorn/no_useless_fallback_in_spread.rs index 4443816b0cde0..08f22767e9b26 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_useless_fallback_in_spread.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_useless_fallback_in_spread.rs @@ -24,15 +24,17 @@ declare_oxc_lint!( /// /// Spreading [falsy values](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) in object literals won't add any unexpected properties, so it's unnecessary to add an empty object as fallback. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const object = { ...(foo || {}) } + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// const object = { ...foo } /// const object = { ...(foo || { not: "empty" }) } - /// /// ``` NoUselessFallbackInSpread, correctness, diff --git a/crates/oxc_linter/src/rules/unicorn/no_useless_promise_resolve_reject.rs b/crates/oxc_linter/src/rules/unicorn/no_useless_promise_resolve_reject.rs index 36c1c3084b78e..d92ab7a38e9ea 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_useless_promise_resolve_reject.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_useless_promise_resolve_reject.rs @@ -38,12 +38,15 @@ declare_oxc_lint!( /// /// Wrapping a return value in `Promise.resolve` in an async function or a `Promise#then`/`catch`/`finally` callback is unnecessary as all return values in async functions and promise callback functions are already wrapped in a `Promise`. Similarly, returning an error wrapped in `Promise.reject` is equivalent to simply `throw`ing the error. This is the same for `yield`ing in async generators as well. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// async () => Promise.resolve(bar); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// async () => bar; /// ``` NoUselessPromiseResolveReject, diff --git a/crates/oxc_linter/src/rules/unicorn/no_useless_switch_case.rs b/crates/oxc_linter/src/rules/unicorn/no_useless_switch_case.rs index 8973007aecdd0..409490ef080e7 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_useless_switch_case.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_useless_switch_case.rs @@ -23,16 +23,20 @@ declare_oxc_lint!( /// /// An empty case before the last default case is useless. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// switch (foo) { /// case 1: /// default: /// handleDefaultCase(); /// break; /// } - /// // good: + /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript /// switch (foo) { /// case 1: /// case 2: diff --git a/crates/oxc_linter/src/rules/unicorn/no_useless_undefined.rs b/crates/oxc_linter/src/rules/unicorn/no_useless_undefined.rs index 84a32efcb0439..56a01a718b7ce 100644 --- a/crates/oxc_linter/src/rules/unicorn/no_useless_undefined.rs +++ b/crates/oxc_linter/src/rules/unicorn/no_useless_undefined.rs @@ -33,17 +33,21 @@ impl Default for NoUselessUndefined { declare_oxc_lint!( /// ### What it does + /// /// Do not use useless `undefined`. /// /// ### Why is this bad? - /// `undefined` is the default value for new variables, parameters, return statements, etc… so specifying it doesn't make any difference. /// + /// `undefined` is the default value for new variables, parameters, return statements, etc… so specifying it doesn't make any difference. /// - /// ### Example + /// ### Examples + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// let foo = undefined; - /// // good: + /// ``` + /// + /// Examples of **correct** code for this rule: + /// ```javascript /// let foo; /// ``` NoUselessUndefined, diff --git a/crates/oxc_linter/src/rules/unicorn/number_literal_case.rs b/crates/oxc_linter/src/rules/unicorn/number_literal_case.rs index afad10c468e0b..83edd6f140a60 100644 --- a/crates/oxc_linter/src/rules/unicorn/number_literal_case.rs +++ b/crates/oxc_linter/src/rules/unicorn/number_literal_case.rs @@ -38,14 +38,17 @@ pub struct NumberLiteralCase; declare_oxc_lint!( /// ### What it does + /// /// This rule enforces proper case for numeric literals. /// /// ### Why is this bad? + /// /// When both an identifier and a number literal are in lower case, it can be hard to differentiate between them. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// const foo = 0XFF; /// const foo = 0xff; /// const foo = 0Xff; @@ -58,8 +61,10 @@ declare_oxc_lint!( /// const foo = 0O76n; /// /// const foo = 2E-5; + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// const foo = 0xFF; /// const foo = 0b10; /// const foo = 0o76; diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_add_event_listener.rs b/crates/oxc_linter/src/rules/unicorn/prefer_add_event_listener.rs index 323b25e4c9bd4..c252b43e2027e 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_add_event_listener.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_add_event_listener.rs @@ -24,12 +24,15 @@ declare_oxc_lint!( /// /// There are [numerous advantages of using `addEventListener`](https://stackoverflow.com/questions/6348494/addeventlistener-vs-onclick/35093997#35093997). Some of these advantages include registering unlimited event handlers and optionally having the event handler invoked only once. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// foo.onclick = () => {}; + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// foo.addEventListener('click', () => {}); /// ``` PreferAddEventListener, diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_code_point.rs b/crates/oxc_linter/src/rules/unicorn/prefer_code_point.rs index ac11c8334ba82..bf0a32a8dff0a 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_code_point.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_code_point.rs @@ -26,13 +26,16 @@ declare_oxc_lint!( /// /// [Difference between `String.fromCodePoint()` and `String.fromCharCode()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCodePoint#compared_to_fromcharcode) /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// '🦄'.charCodeAt(0); /// String.fromCharCode(0x1f984); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// '🦄'.codePointAt(0); /// String.fromCodePoint(0x1f984); /// ``` diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_date_now.rs b/crates/oxc_linter/src/rules/unicorn/prefer_date_now.rs index acdea4b256932..14b45fd0accdb 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_date_now.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_date_now.rs @@ -39,14 +39,15 @@ declare_oxc_lint!( /// /// Using `Date.now()` is shorter and nicer than `new Date().getTime()`, and avoids unnecessary instantiation of `Date` objects. /// - /// - /// ### Example + /// ### Examples + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const ts = new Date().getTime(); /// const ts = new Date().valueOf(); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// const ts = Date.now(); /// ``` PreferDateNow, diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_append.rs b/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_append.rs index d9d5512c43b08..b146287259fd3 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_append.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_append.rs @@ -17,20 +17,21 @@ pub struct PreferDomNodeAppend; declare_oxc_lint!( /// ### What it does /// - ///Enforces the use of, for example, `document.body.append(div);` over `document.body.appendChild(div);` for DOM nodes. + /// Enforces the use of, for example, `document.body.append(div);` over `document.body.appendChild(div);` for DOM nodes. /// /// ### Why is this bad? /// /// There are [some advantages of using `Node#append()`](https://developer.mozilla.org/en-US/docs/Web/API/ParentNode/append), like the ability to append multiple nodes and to append both [`DOMString`](https://developer.mozilla.org/en-US/docs/Web/API/DOMString) and DOM node objects. /// - /// ### Example + /// ### Examples + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// foo.appendChild(bar); + /// ``` /// - // // good + /// Examples of **correct** code for this rule: + /// ```javascript /// foo.append(bar); - // /// ``` PreferDomNodeAppend, pedantic, diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_remove.rs b/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_remove.rs index 5529eef104262..0719e83576daa 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_remove.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_dom_node_remove.rs @@ -28,12 +28,15 @@ declare_oxc_lint!( /// /// The DOM function [`Node#remove()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove) is preferred over the indirect removal of an object with [`Node#removeChild()`](https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild). /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// parentNode.removeChild(childNode); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// childNode.remove(); /// ``` PreferDomNodeRemove, diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_includes.rs b/crates/oxc_linter/src/rules/unicorn/prefer_includes.rs index ad02f1ed691d1..8cc8516bae1c9 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_includes.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_includes.rs @@ -25,19 +25,21 @@ declare_oxc_lint!( /// ### What it does /// /// Prefer `includes()` over `indexOf()` when checking for existence or non-existence. - /// /// All built-ins have `.includes()` in addition to `.indexOf()`. /// /// ### Why is this bad? /// /// The `.includes()` method is more readable and less error-prone than `.indexOf()`. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// if (str.indexOf('foo') !== -1) { } + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// if (str.includes('foo')) { } /// ``` PreferIncludes, diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_native_coercion_functions.rs b/crates/oxc_linter/src/rules/unicorn/prefer_native_coercion_functions.rs index 227bc5ce7a2e3..3121b04251d5d 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_native_coercion_functions.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_native_coercion_functions.rs @@ -32,15 +32,18 @@ declare_oxc_lint!( /// If a function is equivalent to [`String`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), [`Number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt), [`Boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean), or [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol), you should use the built-in one directly. /// Wrapping the built-in in a function is moot. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const foo = v => String(v); /// foo(1); /// const foo = v => Number(v); /// array.some((v, ) => /* comment */ v) + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// String(1); /// Number(1); /// array.some(Boolean); diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_number_properties.rs b/crates/oxc_linter/src/rules/unicorn/prefer_number_properties.rs index 391f79cb70203..2e127631f4f75 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_number_properties.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_number_properties.rs @@ -34,13 +34,16 @@ declare_oxc_lint!( /// - [`Number.POSITIVE_INFINITY`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/POSITIVE_INFINITY) over [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity) /// - [`Number.NEGATIVE_INFINITY`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/NEGATIVE_INFINITY) over [`-Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity) /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const foo = parseInt('10', 2); /// const bar = parseFloat('10.5'); + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// const foo = Number.parseInt('10', 2); /// const bar = Number.parseFloat('10.5'); /// ``` diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_prototype_methods.rs b/crates/oxc_linter/src/rules/unicorn/prefer_prototype_methods.rs index 8c29c27934fcb..7da10aa6453d3 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_prototype_methods.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_prototype_methods.rs @@ -28,16 +28,20 @@ declare_oxc_lint!( /// This rule prefers borrowing methods from the prototype instead of the instance. /// /// ### Why is this bad? + /// /// “Borrowing” a method from an instance of `Array` or `Object` is less clear than getting it from the corresponding prototype. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// const array = [].slice.apply(bar); /// const type = {}.toString.call(foo); /// Reflect.apply([].forEach, arrayLike, [callback]); + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// const array = Array.prototype.slice.apply(bar); /// const type = Object.prototype.toString.call(foo); /// Reflect.apply(Array.prototype.forEach, arrayLike, [callback]); diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_set_size.rs b/crates/oxc_linter/src/rules/unicorn/prefer_set_size.rs index 984375185a4fe..f379ba70b9543 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_set_size.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_set_size.rs @@ -29,14 +29,16 @@ declare_oxc_lint!( /// /// Using `Set#size` is more readable and performant. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const length = [...new Set([1, 2, 3])].length; + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// const size = new Set([1, 2, 3]).size; - /// /// ``` PreferSetSize, correctness, diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_spread.rs b/crates/oxc_linter/src/rules/unicorn/prefer_spread.rs index a7a4b2e278b88..1c05c74a5f58b 100644 --- a/crates/oxc_linter/src/rules/unicorn/prefer_spread.rs +++ b/crates/oxc_linter/src/rules/unicorn/prefer_spread.rs @@ -27,14 +27,18 @@ declare_oxc_lint!( /// /// Using the spread operator is more concise and readable. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// const foo = Array.from(set); /// const foo = Array.from(new Set([1, 2])); + /// ``` /// - /// // good - /// + /// Examples of **correct** code for this rule: + /// ```javascript + /// [...set].map(() => {}); + /// Array.from(...argumentsArray); /// ``` PreferSpread, style, diff --git a/crates/oxc_linter/src/rules/unicorn/require_number_to_fixed_digits_argument.rs b/crates/oxc_linter/src/rules/unicorn/require_number_to_fixed_digits_argument.rs index bcdc83c54d2cb..eb31915aeaf91 100644 --- a/crates/oxc_linter/src/rules/unicorn/require_number_to_fixed_digits_argument.rs +++ b/crates/oxc_linter/src/rules/unicorn/require_number_to_fixed_digits_argument.rs @@ -16,20 +16,25 @@ pub struct RequireNumberToFixedDigitsArgument; declare_oxc_lint!( /// ### What it does + /// /// Enforce using the digits argument with Number.toFixed() /// /// ### Why is this bad? + /// /// It's better to make it clear what the value of the digits argument is when calling Number.toFixed(), /// instead of relying on the default value of 0. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: + /// ```javascript + /// number.toFixed(); + /// ``` + /// + /// Examples of **correct** code for this rule: /// ```javascript - /// // Pass /// number.toFixed(0); /// number.toFixed(2); - /// - /// // Fail: - /// number.toFixed(); /// ``` RequireNumberToFixedDigitsArgument, pedantic, diff --git a/crates/oxc_linter/src/rules/unicorn/throw_new_error.rs b/crates/oxc_linter/src/rules/unicorn/throw_new_error.rs index 3187513c7b4dd..7d0aedc0f0ff6 100644 --- a/crates/oxc_linter/src/rules/unicorn/throw_new_error.rs +++ b/crates/oxc_linter/src/rules/unicorn/throw_new_error.rs @@ -33,18 +33,20 @@ declare_oxc_lint!( /// /// While it's possible to create a new error without using the `new` keyword, it's better to be explicit. /// - /// ### Example + /// ### Examples + /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // Fail /// throw Error('🦄'); /// throw TypeError('unicorn'); /// throw lib.TypeError('unicorn'); + /// ``` /// - /// // Pass + /// Examples of **correct** code for this rule: + /// ```javascript /// throw new Error('🦄'); /// throw new TypeError('unicorn'); /// throw new lib.TypeError('unicorn'); - /// /// ``` ThrowNewError, style,