docs(linter): improve documentation for several rules

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

@@ -26,16 +26,55 @@ pub struct ForDirection;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// Disallow "for" loop update causing the counter to move in the wrong direction.
+    /// Disallow `for` loop update causing the counter to move in the wrong direction.
     ///
     /// ### Why is this bad?
-    /// A for loop that is known to run infinitely or never run is considered a bug.
+    /// A `for` loop with a stop condition that can never be reached, such as one
+    /// with a counter that moves in the wrong direction, will run infinitely.
+    /// While there are occasions when an infinite loop is intended, the
+    /// convention is to construct such loops as `while` loops. More typically, an
+    /// infinite `for` loop is a bug.
+    ///
+    /// This rule forbids `for` loops where the counter variable changes in such a
+    /// way that the stop condition will never be met. For example, if the
+    /// counter variable is increasing (i.e. `i++``) and the stop condition tests
+    /// that the counter is greater than zero (`i >= 0``) then the loop will never
+    /// exit.
     ///
     /// ### Example
-    /// ```javascript
-    /// for (var i = 0; i < 10; i--) {}
     ///
-    /// for (var i = 10; i >= 0; i++) {}
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
+    /// for (var i = 0; i < 10; i--) {
+    /// }
+    ///
+    /// for (var i = 10; i >= 0; i++) {
+    /// }
+    ///
+    /// for (var i = 0; i > 10; i++) {
+    /// }
+    ///
+    /// for (var i = 0; 10 > i; i--) {
+    /// }
+    ///
+    /// const n = -2;
+    /// for (let i = 0; i < 10; i += n) {
+    /// }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// for (var i = 0; i < 10; i++) {
+    /// }
+    ///
+    /// for (var i = 0; 10 > i; i++) { // with counter "i" on the right
+    /// }
+    ///
+    /// for (let i = 10; i >= 0; i += this.step) { // direction unknown
+    /// }
+    ///
+    /// for (let i = MIN; i <= MAX; i -= 0) { // not increasing or decreasing
+    /// }
     /// ```
     ForDirection,
     correctness,

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

@@ -17,15 +17,29 @@ pub struct NoCaller;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Disallow the use of arguments.caller or arguments.callee
+    /// Disallow the use of `arguments.caller` or `arguments.callee`.
     ///
     /// ### Why is this bad?
     ///
-    /// The use of arguments.caller and arguments.callee make several code optimizations impossible.
-    /// They have been deprecated in future versions of JavaScript and their use is forbidden in ECMAScript 5 while in strict mode.
+    /// The use of `arguments.caller` and `arguments.callee` make several code
+    /// optimizations impossible.  They have been deprecated in future versions
+    /// of JavaScript and their use is forbidden in ECMAScript 5 while in strict
+    /// mode.
+    ///
+    /// ```js
+    /// function foo() {
+    /// var callee = arguments.callee;
+    /// }
+    /// ```
+    ///
+    /// This rule is aimed at discouraging the use of deprecated and sub-optimal
+    /// code by disallowing the use of `arguments.caller` and `arguments.callee`. As
+    /// such, it will warn when `arguments.caller` and `arguments.callee` are used.
     ///
     /// ### Example
-    /// ```javascript
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
     /// function foo(n) {
     ///     if (n <= 0) {
     ///         return;
@@ -38,6 +52,21 @@ declare_oxc_lint!(
     ///    return !(n > 1) ? 1 : arguments.callee(n - 1) * n;
     /// });
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// function foo(n) {
+    ///     if (n <= 0) {
+    ///         return;
+    ///     }
+    ///
+    ///     foo(n - 1);
+    /// }
+    ///
+    /// [1,2,3,4,5].map(function factorial(n) {
+    ///     return !(n > 1) ? 1 : factorial(n - 1) * n;
+    /// });
+    /// ```
     NoCaller,
     correctness
 );

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

@@ -17,16 +17,30 @@ pub struct NoConstAssign;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// Disallow reassigning const variables
+    /// Disallow reassigning `const` variables.
     ///
     /// ### Why is this bad?
     /// We cannot modify variables that are declared using const keyword.
     /// It will raise a runtime error.
     ///
     /// ### Example
-    /// ```javascript
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
     /// const a = 0;
     /// a = 1;
+    ///
+    /// const b = 0;
+    /// b += 1;
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// const a = 0;
+    /// console.log(a);
+    ///
+    /// var b = 0;
+    /// b += 1;
     /// ```
     NoConstAssign,
     correctness

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

@@ -22,13 +22,13 @@ declare_oxc_lint!(
     /// Disallow expressions where the operation doesn't affect the value
     ///
     /// ### Why is this bad?
-    /// Comparisons which will always evaluate to true or false and logical expressions (||, &&, ??) which either always
+    /// Comparisons which will always evaluate to true or false and logical expressions (`||`, `&&`, `??`) which either always
     /// short-circuit or never short-circuit are both likely indications of programmer error.
     ///
     /// These errors are especially common in complex expressions where operator precedence is easy to misjudge.
     ///
     /// Additionally, this rule detects comparisons to newly constructed objects/arrays/functions/etc.
-    /// In JavaScript, where objects are compared by reference, a newly constructed object can never === any other value.
+    /// In JavaScript, where objects are compared by reference, a newly constructed object can never `===` any other value.
     /// This can be surprising for programmers coming from languages where objects are compared by value.
     ///
     /// ### Example

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

@@ -23,14 +23,44 @@ declare_oxc_lint!(
     ///
     /// ### Why is this bad?
     ///
-    /// A constant expression (for example, a literal) as a test condition might be a typo or development trigger for a specific behavior.
+    /// A constant expression (for example, a literal) as a test condition might
+    /// be a typo or development trigger for a specific behavior.
+    ///
+    /// This rule disallows constant expressions in the test condition of:
+    ///
+    /// - `if`, `for`, `while`, or `do...while` statement
+    /// - `?`: ternary expression
+    ///
     ///
     /// ### Example
     ///
-    /// ```javascript
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
     /// if (false) {
     ///    doSomethingUnfinished();
     /// }
+    ///
+    /// if (new Boolean(x)) {
+    ///     doSomethingAlways();
+    /// }
+    /// if (x ||= true) {
+    ///     doSomethingAlways();
+    /// }
+    ///
+    /// do {
+    ///     doSomethingForever();
+    /// } while (x = -1);
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// if (x === 0) {
+    ///     doSomething();
+    /// }
+    ///
+    /// while (typeof x === "undefined") {
+    ///     doSomething();
+    /// }
     /// ```
     NoConstantCondition,
     correctness

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

@@ -16,13 +16,17 @@ pub struct NoDeleteVar;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// The purpose of the delete operator is to remove a property from an object.
+    /// The purpose of the `delete` operator is to remove a property from an
+    /// object.
     ///
     /// ### Why is this bad?
     ///
-    /// Using the delete operator on a variable might lead to unexpected behavior.
+    /// Using the `delete` operator on a variable might lead to unexpected
+    /// behavior.
     ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// var x;
     /// delete x;

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

@@ -19,17 +19,32 @@ declare_oxc_lint!(
     /// Disallows the usages of empty static blocks
     ///
     /// ### Why is this bad?
-    /// Empty block statements, while not technically errors, usually occur due to refactoring that wasn’t completed.
-    /// They can cause confusion when reading code.
+    /// Empty block statements, while not technically errors, usually occur due
+    /// to refactoring that wasn’t completed.  They can cause confusion when
+    /// reading code.
     ///
     /// ### Example
-    /// ```javascript
     ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
     /// class Foo {
     ///     static {
     ///     }
     /// }
+    /// ```
     ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// class Foo {
+    ///     static {
+    ///         // blocks with comments are allowed
+    ///     }
+    /// }
+    /// class Bar {
+    ///     static {
+    ///         doSomething();
+    ///     }
+    /// }
     /// ```
     NoEmptyStaticBlock,
     correctness

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

@@ -19,15 +19,37 @@ pub struct NoEqNull;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// Disallow null comparisons without type-checking operators.
+    /// Disallow `null` comparisons without type-checking operators.
     ///
     /// ### Why is this bad?
-    /// Comparing to null without a type-checking operator (== or !=), can have unintended results as the comparison will evaluate to true when comparing to not just a null, but also an undefined value.
+    /// Comparing to `null` without a type-checking operator (`==` or `!=`), can
+    /// have unintended results as the comparison will evaluate to `true` when
+    /// comparing to not just a `null`, but also an `undefined` value.
     ///
     /// ### Example
-    /// ```javascript
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
     /// if (foo == null) {
-    ///   bar();
+    ///     bar();
+    /// }
+    /// if (baz != null) {
+    ///     bar();
+    /// }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// if (foo === null) {
+    ///     bar();
+    /// }
+    ///
+    /// if (baz !== null) {
+    ///     bar();
+    /// }
+    ///
+    /// if (bang === undefined) {
+    ///     bar();
     /// }
     /// ```
     NoEqNull,

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

@@ -16,20 +16,41 @@ pub struct NoIterator;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// Disallow the use of the __iterator__ property
+    /// Disallow the use of the `__iterator__` property
     ///
     /// ### Why is this bad?
-    /// The __iterator__ property was a SpiderMonkey extension to JavaScript
+    /// The `__iterator__` property was a SpiderMonkey extension to JavaScript
     /// that could be used to create custom iterators that are compatible with
     /// JavaScript’s for in and for each constructs. However, this property is
     /// now obsolete, so it should not be used. Here’s an example of how this
     /// used to work:
     ///
+    /// ```js
+    /// Foo.prototype.__iterator__ = function() {
+    ///     return new FooIterator(this);
+    /// }
+    /// ```
+    ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// Foo.prototype.__iterator__ = function() {
     ///     return new FooIterator(this);
-    /// }
+    /// };
+    ///
+    /// foo.__iterator__ = function () {};
+    ///
+    /// foo["__iterator__"] = function () {};
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// const __iterator__ = 42; // not using the __iterator__ property
+    ///
+    /// Foo.prototype[Symbol.iterator] = function() {
+    ///    return new FooIterator(this);
+    /// };
     /// ```
     NoIterator,
     restriction

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

@@ -29,7 +29,6 @@ declare_oxc_lint!(
     /// ### Example
     ///
     /// Examples of **incorrect** code for this rule:
-    ///
     /// ```js
     /// var x = foo;
     /// function bar() {
@@ -39,8 +38,8 @@ declare_oxc_lint!(
     ///   }
     /// }
     /// ```
-    /// Examples of **correct** code for this rule:
     ///
+    /// Examples of **correct** code for this rule:
     /// ```js
     /// // The variable that has the same name as the label is not in scope.
     ///