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

![jim carrey typing](https://github.com/user-attachments/assets/dd18d89f-7aa3-42b6-b004-65e0d44cb6b1)

Ok I lied, it's 26 unicorn rules and 1 vue rule. Sorry.

No AI here :)

This PR generally improves the documentation for all of these rules to provide more examples, improved explanations for the rules' purposes, and so on.

It also adds MDN links where relevant via new diagnostic notes.

(note: if this gets merged before the release but after the website PR is generated, make sure to regenerate the website PR 🙂)

Author: connorshea

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,