docs(linter): Improve rule docs for 27 unicorn rules

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

@@ -10,8 +10,8 @@ use oxc_span::Span;
 use crate::{AstNode, context::LintContext, rule::Rule};
 
 fn consistent_assert_diagnostic(assert_identifier: &str, span: Span) -> OxcDiagnostic {
-    OxcDiagnostic::warn("Inconsistent assert usage")
-        .with_help(format!("Prefer {assert_identifier}.ok(...) over {assert_identifier}(...)"))
+    OxcDiagnostic::warn("Inconsistent assert usage.")
+        .with_help(format!("Prefer `{assert_identifier}.ok(...)` over `{assert_identifier}(...)`."))
         .with_label(span)
 }
 
@@ -25,7 +25,11 @@ declare_oxc_lint!(
     ///
     /// ### Why is this bad?
     ///
-    /// Inconsistent usage of the `assert` module can lead to confusion and errors.
+    /// Inconsistent usage of the `assert` module can make code
+    /// harder to follow and understand.
+    ///
+    /// `assert.ok(...)` is preferred as it makes the intent of
+    /// the assertion clearer.
     ///
     /// ### Examples
     ///

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

@@ -58,10 +58,14 @@ pub struct ExplicitLengthCheck {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Enforce explicitly comparing the length or size property of a value.
+    /// Enforce explicitly comparing the `length` or `size` property of a value.
     ///
     /// ### Why is this bad?
     ///
+    /// Using the explicit `length` or `size` properties can help make code clearer
+    /// and easier to understand, as it avoids relying on implicit truthy/falsy
+    /// evaluations.
+    ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
@@ -80,6 +84,10 @@ declare_oxc_lint!(
     /// Examples of **correct** code for this rule:
     /// ```javascript
     /// const isEmpty = foo.length === 0;
+    ///
+    /// if (foo.length > 0 || bar.length > 0) {}
+    ///
+    /// const unicorn = foo.length > 0 ? 1 : 2;
     /// ```
     ExplicitLengthCheck,
     unicorn,

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

@@ -29,30 +29,43 @@ pub struct NoAccessorRecursion;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow recursive access to this within getters and setters
+    /// Disallow recursive access to `this` within getters and setters.
     ///
     /// ### Why is this bad?
     ///
-    /// This rule prevents recursive access to this within getter and setter methods in objects and classes,
-    ///  avoiding infinite recursion and stack overflow errors.
+    /// This rule prevents recursive access to `this` within getter and
+    /// setter methods in objects and classes, avoiding infinite recursion
+    /// and stack overflow errors.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```js
     /// const foo = {
-    /// 	get bar() {
-    /// 		return this.bar;
-    /// 	}
+    ///   get bar() {
+    ///     return this.bar;
+    ///   }
+    /// };
+    ///
+    /// const baz = {
+    ///   set bar(value) {
+    ///     this.bar = value;
+    ///   }
     /// };
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```js
     /// const foo = {
-    /// 	get bar() {
-    /// 		return this.baz;
-    /// 	}
+    ///   get bar() {
+    ///     return this.qux;
+    ///   }
+    /// };
+    ///
+    /// const baz = {
+    ///   set bar(value) {
+    ///     this._bar = value;
+    ///   }
     /// };
     /// ```
     NoAccessorRecursion,

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

@@ -30,7 +30,9 @@ declare_oxc_lint!(
     ///
     /// ### Why is this bad?
     ///
-    /// The `console.log()` method and similar methods join the parameters with a space so adding a leading/trailing space to a parameter, results in two spaces being added.
+    /// The `console.log()` method and similar methods join the parameters
+    /// with a space so adding a leading/trailing space to a parameter,
+    /// results in two spaces being added.
     ///
     /// ### Examples
     ///

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

@@ -12,8 +12,9 @@ use crate::{
 };
 
 fn no_document_cookie_diagnostic(span: Span) -> OxcDiagnostic {
-    OxcDiagnostic::warn("Do not use `document.cookie` directly")
-        .with_help("Use the Cookie Store API or a cookie library instead")
+    OxcDiagnostic::warn("Do not use `document.cookie` directly.")
+        .with_help("Use the Cookie Store API or a cookie library instead.")
+        .with_note("https://developer.mozilla.org/en-US/docs/Web/API/Cookie_Store_API")
         .with_label(span)
 }
 
@@ -23,7 +24,7 @@ pub struct NoDocumentCookie;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow direct use of
+    /// Disallows direct use of
     /// [`document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie).
     ///
     /// ### Why is this bad?
@@ -33,7 +34,7 @@ declare_oxc_lint!(
     /// directly as it's easy to get the string wrong. Instead, you should use
     /// the [Cookie Store
     /// API](https://developer.mozilla.org/en-US/docs/Web/API/Cookie_Store_API)
-    /// or a [cookie library](https://www.npmjs.com/search?q=cookie).
+    /// or a [cookie library](https://npmx.dev/search?q=cookie).
     ///
     /// ### Examples
     ///

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

@@ -22,10 +22,15 @@ pub struct NoHexEscape;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// 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.
+    /// 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.
     ///
     /// ### Why is this bad?
     ///
+    /// Using hexadecimal escapes can be less readable and harder to understand
+    /// when compared to Unicode escapes.
+    ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:

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

@@ -22,7 +22,8 @@ declare_oxc_lint!(
     ///
     /// ### Why is this bad?
     ///
-    /// The instanceof Array check doesn't work across realms/contexts, for example, frames/windows in browsers or the vm module in Node.js.
+    /// The `instanceof Array` check doesn't work across realms/contexts.
+    /// For example, frames/windows in browsers or the `vm` module in Node.js.
     ///
     /// ### Examples
     ///

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

@@ -40,16 +40,16 @@ declare_oxc_lint!(
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// const response = await fetch('/', {method: 'GET', body: 'foo=bar'});
+    /// const response = await fetch('/', { method: 'GET', body: 'foo=bar' });
     ///
-    /// const request = new Request('/', {method: 'GET', body: 'foo=bar'});
+    /// const request = new Request('/', { method: 'GET', body: 'foo=bar' });
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
-    /// const response = await fetch('/', {method: 'POST', body: 'foo=bar'});
+    /// const response = await fetch('/', { method: 'POST', body: 'foo=bar' });
     ///
-    /// const request = new Request('/', {method: 'POST', body: 'foo=bar'});
+    /// const request = new Request('/', { method: 'POST', body: 'foo=bar' });
     /// ```
     NoInvalidFetchOptions,
     unicorn,

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

@@ -20,11 +20,15 @@ pub struct NoMagicArrayFlatDepth;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow magic numbers for `Array.prototype.flat` depth.
+    /// Disallow magic numbers for [`Array.prototype.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat)
+    /// depth.
     ///
     /// ### Why is this bad?
     ///
-    /// Magic numbers are hard to understand and maintain. When calling `Array.prototype.flat`, it is usually called with `1` or infinity. If you are using a different number, it is better to add a comment explaining the depth.
+    /// Magic numbers are hard to understand and maintain.
+    /// When calling `Array.prototype.flat`, it is usually called with
+    /// `1` or `Infinity`. If you are using a different number, it is
+    /// better to add a comment explaining the reason for the depth provided.
     ///
     /// ### Examples
     ///

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

@@ -17,27 +17,34 @@ pub struct NoProcessExit;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow `process.exit()`.
+    /// Disallow all usage of `process.exit()`.
     ///
     /// ### Why is this bad?
     ///
-    /// Only use `process.exit()` in CLI apps. Throw an error instead.
+    /// `process.exit()` should generally only be used in command-line utilities. In all other
+    /// types of applications, the code should throw an error instead.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// if (problem) process.exit(1);
+    /// if (problem) {
+    ///   process.exit(1);
+    /// }
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
-    /// if (problem) throw new Error("message");
+    /// if (problem) {
+    ///   throw new Error("message");
+    /// }
     /// ```
     ///
     /// ```
     /// #!/usr/bin/env node
-    /// if (problem) process.exit(1);
+    /// if (problem) {
+    ///   process.exit(1);
+    /// }
     /// ```
     NoProcessExit,
     unicorn,

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

@@ -23,7 +23,7 @@ pub struct NoSinglePromiseInPromiseMethods;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow passing single-element arrays to Promise methods
+    /// Disallow passing single-element arrays to `Promise` methods.
     ///
     /// ### Why is this bad?
     ///
@@ -35,21 +35,21 @@ declare_oxc_lint!(
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// async function bad() {
-    ///     const foo = await Promise.all([promise]);
-    ///     const foo = await Promise.any([promise]);
-    ///     const foo = await Promise.race([promise]);
-    ///     const promise = Promise.all([nonPromise]);
+    ///   const foo = await Promise.all([promise]);
+    ///   const foo = await Promise.any([promise]);
+    ///   const foo = await Promise.race([promise]);
+    ///   const promise = Promise.all([nonPromise]);
     /// }
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
     /// async function good() {
-    ///     const foo = await promise;
-    ///     const promise = Promise.resolve(nonPromise);
-    ///     const foo = await Promise.all(promises);
-    ///     const foo = await Promise.any([promise, anotherPromise]);
-    ///     const [{ value: foo, reason: error }] = await Promise.allSettled([promise]);
+    ///   const foo = await promise;
+    ///   const promise = Promise.resolve(nonPromise);
+    ///   const foo = await Promise.all(promises);
+    ///   const foo = await Promise.any([promise, anotherPromise]);
+    ///   const [{ value: foo, reason: error }] = await Promise.allSettled([promise]);
     /// }
     /// ```
     NoSinglePromiseInPromiseMethods,

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

@@ -6,7 +6,7 @@ use oxc_span::{GetSpan, Span};
 use crate::{AstNode, context::LintContext, rule::Rule};
 
 fn no_static_only_class_diagnostic(span: Span) -> OxcDiagnostic {
-    OxcDiagnostic::warn("Use an object instead of a class with only static members.")
+    OxcDiagnostic::warn("Use an object instead of a `class` with only `static` members.")
         .with_label(span)
 }
 
@@ -16,39 +16,39 @@ pub struct NoStaticOnlyClass;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow classes that only have static members.
+    /// Disallow `class` declarations that exclusively contain `static` members.
     ///
     /// ### Why is this bad?
     ///
-    /// A class with only static members could just be an object instead.
+    /// A `class` with only `static` members should just be defined as an object instead.
     ///
     /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// class A {
-    ///     static a() {}
+    ///   static a() {}
     /// }
     /// ```
     ///
     /// Examples of **correct** code for this rule:
     /// ```javascript
     /// class A {
-    ///     static a() {}
+    ///   static a() {}
     ///
-    ///     constructor() {}
+    ///   constructor() {}
     /// }
     /// ```
     /// ```javascript
     /// const X = {
-    ///     foo: false,
-    ///     bar() {}
+    ///   foo: false,
+    ///   bar() {}
     /// };
     /// ```
     /// ```javascript
     /// class X {
-    ///     static #foo = false; // private field
-    ///     static bar() {}
+    ///   static #foo = false; // private field
+    ///   static bar() {}
     /// }
     /// ```
     NoStaticOnlyClass,