diff --git a/crates/oxc_linter/src/rules/eslint/no_empty.rs b/crates/oxc_linter/src/rules/eslint/no_empty.rs
index 4dba955b8487c..84a402ad0c5d7 100644
--- a/crates/oxc_linter/src/rules/eslint/no_empty.rs
+++ b/crates/oxc_linter/src/rules/eslint/no_empty.rs
@@ -32,6 +32,7 @@ declare_oxc_lint!(
     /// ```
     NoEmpty,
     restriction,
+    pending // a suggestion could be added to remove the empty statement
 );
 
 impl Rule for NoEmpty {
diff --git a/crates/oxc_linter/src/rules/eslint/no_extra_boolean_cast.rs b/crates/oxc_linter/src/rules/eslint/no_extra_boolean_cast.rs
index 8e1383da944d0..559c70de574d0 100644
--- a/crates/oxc_linter/src/rules/eslint/no_extra_boolean_cast.rs
+++ b/crates/oxc_linter/src/rules/eslint/no_extra_boolean_cast.rs
@@ -44,7 +44,10 @@ declare_oxc_lint!(
     /// if (!!foo || bar) {}
     /// ```
     NoExtraBooleanCast,
-    correctness
+    correctness,
+    // a suggestion could be added. Note that lacking !! can mess up TS type
+    // narrowing sometimes, so it should not be an autofix
+    pending
 );
 
 impl Rule for NoExtraBooleanCast {
diff --git a/crates/oxc_linter/src/rules/eslint/no_fallthrough.rs b/crates/oxc_linter/src/rules/eslint/no_fallthrough.rs
index 32396f973d111..b0d2bc256851b 100644
--- a/crates/oxc_linter/src/rules/eslint/no_fallthrough.rs
+++ b/crates/oxc_linter/src/rules/eslint/no_fallthrough.rs
@@ -73,8 +73,177 @@ declare_oxc_lint!(
     ///
     /// Disallow fallthrough of `case` statements
     ///
+    /// This rule is aimed at eliminating unintentional fallthrough of one case
+    /// to the other. As such, it flags any fallthrough scenarios that are not
+    /// marked by a comment.
+    ///
+    /// ### Why is this bad?
+    ///
+    /// The switch statement in JavaScript is one of the more error-prone
+    /// constructs of the language thanks in part to the ability to “fall
+    /// through” from one case to the next. For example:
+    ///
+    /// ```js
+    /// switch(foo) {
+    ///     case 1:
+    ///     doSomething();
+    ///
+    /// case 2:
+    ///     doSomethingElse();
+    /// }
+    /// ```
+    ///
+    /// In this example, if `foo` is `1`, then execution will flow through both
+    /// cases, as the first falls through to the second. You can prevent this by
+    /// using `break`, as in this example:
+    ///
+    /// ```js
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         break;
+    ///
+    ///     case 2:
+    ///         doSomethingElse();
+    /// }
+    /// ```
+    ///
+    /// That works fine when you don’t want a fallthrough, but what if the
+    /// fallthrough is intentional, there is no way to indicate that in the
+    /// language. It’s considered a best practice to always indicate when a
+    /// fallthrough is intentional using a comment which matches the
+    /// `/falls?\s?through/i`` regular expression but isn’t a directive:
+    ///
+    /// ```js
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         // falls through
+    ///
+    ///     case 2:
+    ///         doSomethingElse();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         // fall through
+    ///
+    ///     case 2:
+    ///         doSomethingElse();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         // fallsthrough
+    ///
+    ///     case 2:
+    ///         doSomethingElse();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1: {
+    ///         doSomething();
+    ///         // falls through
+    ///     }
+    ///
+    ///     case 2: {
+    ///         doSomethingElse();
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// In this example, there is no confusion as to the expected behavior. It
+    /// is clear that the first case is meant to fall through to the second
+    /// case.
+    ///
+    /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```js
+    /// /*oxlint no-fallthrough: "error"*/
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///
+    ///     case 2:
+    ///         doSomething();
+    /// }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```js
+    /// /*oxlint no-fallthrough: "error"*/
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         break;
+    ///
+    ///     case 2:
+    ///         doSomething();
+    /// }
+    ///
+    /// function bar(foo) {
+    ///     switch(foo) {
+    ///         case 1:
+    ///             doSomething();
+    ///             return;
+    ///
+    ///         case 2:
+    ///             doSomething();
+    ///     }
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         throw new Error("Boo!");
+    ///
+    ///     case 2:
+    ///         doSomething();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///     case 2:
+    ///         doSomething();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1: case 2:
+    ///         doSomething();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1:
+    ///         doSomething();
+    ///         // falls through
+    ///
+    ///     case 2:
+    ///         doSomething();
+    /// }
+    ///
+    /// switch(foo) {
+    ///     case 1: {
+    ///         doSomething();
+    ///         // falls through
+    ///     }
+    ///
+    ///     case 2: {
+    ///         doSomethingElse();
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// Note that the last case statement in these examples does not cause a
+    /// warning because there is nothing to fall through into.
     NoFallthrough,
-    pedantic // Fall through code are still incorrect.
+    // TODO: add options section to docs
+    pedantic, // Fall through code are still incorrect.
+    pending // TODO: add a dangerous suggestion for this rule.
 );
 
 impl Rule for NoFallthrough {
diff --git a/crates/oxc_linter/src/rules/eslint/no_iterator.rs b/crates/oxc_linter/src/rules/eslint/no_iterator.rs
index 4dd59842f10e1..f3322ba61fe0e 100644
--- a/crates/oxc_linter/src/rules/eslint/no_iterator.rs
+++ b/crates/oxc_linter/src/rules/eslint/no_iterator.rs
@@ -19,7 +19,11 @@ declare_oxc_lint!(
     /// Disallow the use of the __iterator__ property
     ///
     /// ### Why is this bad?
-    /// 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:
+    /// 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:
     ///
     /// ### Example
     /// ```javascript
diff --git a/crates/oxc_linter/src/rules/eslint/no_label_var.rs b/crates/oxc_linter/src/rules/eslint/no_label_var.rs
index 304338a6b2f29..4ac1d74a7335b 100644
--- a/crates/oxc_linter/src/rules/eslint/no_label_var.rs
+++ b/crates/oxc_linter/src/rules/eslint/no_label_var.rs
@@ -27,7 +27,10 @@ declare_oxc_lint!(
     /// that shares a name with a variable that is in scope.
     ///
     /// ### Example
-    /// ```javascript
+    ///
+    /// Examples of **incorrect** code for this rule:
+    ///
+    /// ```js
     /// var x = foo;
     /// function bar() {
     /// x:
@@ -36,6 +39,22 @@ declare_oxc_lint!(
     ///   }
     /// }
     /// ```
+    /// Examples of **correct** code for this rule:
+    ///
+    /// ```js
+    /// // The variable that has the same name as the label is not in scope.
+    ///
+    /// function foo() {
+    ///     var q = t;
+    /// }
+    ///
+    /// function bar() {
+    /// q:
+    ///     for(;;) {
+    ///         break q;
+    ///     }
+    /// }
+    /// ```
     NoLabelVar,
     style,
 );
diff --git a/crates/oxc_linter/src/rules/eslint/no_var.rs b/crates/oxc_linter/src/rules/eslint/no_var.rs
index e650f3aec168a..2bdfb8aca803c 100644
--- a/crates/oxc_linter/src/rules/eslint/no_var.rs
+++ b/crates/oxc_linter/src/rules/eslint/no_var.rs
@@ -20,8 +20,11 @@ pub struct NoVar;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// ECMAScript 6 allows programmers to create variables with block scope instead of function scope using the `let` and `const` keywords.
-    /// Block scope is common in many other programming languages and helps programmers avoid mistakes
+    ///
+    /// ECMAScript 6 allows programmers to create variables with block scope
+    /// instead of function scope using the `let` and `const` keywords.  Block
+    /// scope is common in many other programming languages and helps
+    /// programmers avoid mistakes.
     ///
     /// ### Why is this bad?
     /// Using `var` in an es6 environment triggers this error
@@ -37,7 +40,8 @@ declare_oxc_lint!(
     /// const CONFIG = {};
     /// ```
     NoVar,
-    restriction
+    restriction,
+    pending // TODO: add suggestion that replaces `var` with `let` or `const` depending on if its written to
 );
 
 impl Rule for NoVar {
diff --git a/crates/oxc_linter/src/rules/eslint/require_await.rs b/crates/oxc_linter/src/rules/eslint/require_await.rs
index 9e5cd5d7014d8..004d492160ebc 100644
--- a/crates/oxc_linter/src/rules/eslint/require_await.rs
+++ b/crates/oxc_linter/src/rules/eslint/require_await.rs
@@ -19,15 +19,52 @@ fn require_await_diagnostic(span0: Span) -> OxcDiagnostic {
 
 declare_oxc_lint!(
     /// ### What it does
-    /// Disallow async functions which have no await expression.
+    ///
+    /// Disallow async functions which have no `await` expression.
     ///
     /// ### Why is this bad?
     ///
+    /// Asynchronous functions in JavaScript behave differently than other
+    /// functions in two important ways:
+    ///
+    /// 1. The return value is always a `Promise`.
+    /// 2. You can use the `await` operator inside of them.
+    ///
+    /// The primary reason to use asynchronous functions is typically to use the
+    /// await operator, such as this:
+    ///
+    /// ```js
+    /// async function fetchData(processDataItem) {
+    ///     const response = await fetch(DATA_URL);
+    ///     const data = await response.json();
+    ///
+    ///     return data.map(processDataItem);
+    /// }
+    /// ```
+    /// Asynchronous functions that don’t use await might not need to be
+    /// asynchronous functions and could be the unintentional result of
+    /// refactoring.
+    ///
+    /// Note: this rule ignores async generator functions. This is because
+    /// generators yield rather than return a value and async generators might
+    /// yield all the values of another async generator without ever actually
+    /// needing to use await.
     ///
     /// ### Example
-    /// ```javascript
+    ///
+    /// Examples of **incorrect** code for this rule:
+    ///
+    /// ```js
+    /// async function foo() {
+    ///     doSomething();
+    /// }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    ///
+    /// ```js
     /// async function foo() {
-    ///   doSomething();
+    ///    await doSomething();
     /// }
     /// ```
     RequireAwait,
diff --git a/crates/oxc_linter/src/rules/eslint/symbol_description.rs b/crates/oxc_linter/src/rules/eslint/symbol_description.rs
index 4b191b91fc52b..b3beafc643810 100644
--- a/crates/oxc_linter/src/rules/eslint/symbol_description.rs
+++ b/crates/oxc_linter/src/rules/eslint/symbol_description.rs
@@ -21,10 +21,27 @@ declare_oxc_lint!(
     ///
     /// The Symbol function may have an optional description.
     ///
+    /// ```js
+    /// var foo = Symbol("some description");
+    ///
+    /// var someString = "some description";
+    /// var bar = Symbol(someString);
+    /// ```
+    ///
+    /// Using `description` promotes easier debugging: when a symbol is logged the description is used:
+    /// ```js
+    /// var foo = Symbol("some description");
+    ///
+    /// console.log(foo);
+    /// // prints - Symbol(some description)
+    /// ```
+    ///
     /// ### Example
     /// ```javascript
     /// var foo = Symbol();
     /// ```
+    ///
+    ///
     SymbolDescription,
     pedantic,
 );
diff --git a/crates/oxc_linter/src/rules/eslint/valid_typeof.rs b/crates/oxc_linter/src/rules/eslint/valid_typeof.rs
index 4ac9d1fb35435..f0e750ac4d5c7 100644
--- a/crates/oxc_linter/src/rules/eslint/valid_typeof.rs
+++ b/crates/oxc_linter/src/rules/eslint/valid_typeof.rs
@@ -34,18 +34,20 @@ declare_oxc_lint!(
     /// Enforce comparing `typeof` expressions against valid strings
     ///
     /// ### Why is this bad?
-    /// It is usually a typing mistake to compare the result of a typeof operator to other string literals.
+    /// It is usually a typing mistake to compare the result of a `typeof`
+    /// operator to other string literals.
+    ///
     /// ### Example
-    /// ```javascript
-    /// requireStringLiterals: false
-    /// incorrect:
+    /// ```js
+    /// // requireStringLiterals: false
+    /// // incorrect:
     /// typeof foo === "strnig"
-    /// correct:
+    /// // correct:
     /// typeof foo === "string"
     /// typeof foo === baz
     ///
-    /// requireStringLiterals: true
-    /// incorrect:
+    /// // requireStringLiterals: true
+    /// // incorrect:
     /// typeof foo === baz
     /// ```
     ValidTypeof,
diff --git a/crates/oxc_linter/src/rules/oxc/missing_throw.rs b/crates/oxc_linter/src/rules/oxc/missing_throw.rs
index 6c23841baf8f8..27fe633f8ba49 100644
--- a/crates/oxc_linter/src/rules/oxc/missing_throw.rs
+++ b/crates/oxc_linter/src/rules/oxc/missing_throw.rs
@@ -25,7 +25,8 @@ declare_oxc_lint!(
     /// const foo = () => { new Error() }
     /// ```
     MissingThrow,
-    correctness
+    correctness,
+    pending // TODO: add a suggestion that adds `throw`
 );
 
 impl Rule for MissingThrow {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_array_flat.rs b/crates/oxc_linter/src/rules/unicorn/prefer_array_flat.rs
index 59dd23e0315ff..2c47dbf68b393 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_array_flat.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_array_flat.rs
@@ -31,7 +31,7 @@ pub struct PreferArrayFlat;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Prefers `Array#flat()` over legacy techniques to flatten arrays.    ///
+    /// Prefers `Array#flat()` over legacy techniques to flatten arrays.
     ///
     /// ### Why is this bad?
     ///
@@ -57,7 +57,8 @@ declare_oxc_lint!(
     /// const foo = [maybeArray].flat();
     /// ```
     PreferArrayFlat,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferArrayFlat {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_array_some.rs b/crates/oxc_linter/src/rules/unicorn/prefer_array_some.rs
index e41a75b025e98..07dc81d8bc381 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_array_some.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_array_some.rs
@@ -45,7 +45,8 @@ declare_oxc_lint!(
     /// const foo = array.some(fn) ? bar : baz;
     /// ```
     PreferArraySome,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferArraySome {
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 ee4abd5420575..6b09bf679bfa1 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_date_now.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_date_now.rs
@@ -50,7 +50,8 @@ declare_oxc_lint!(
     /// const ts = Date.now();
     /// ```
     PreferDateNow,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferDateNow {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_modern_math_apis.rs b/crates/oxc_linter/src/rules/unicorn/prefer_modern_math_apis.rs
index c43bf86fe3dd0..4f8c7252c43f2 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_modern_math_apis.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_modern_math_apis.rs
@@ -51,6 +51,7 @@ declare_oxc_lint!(
     /// ```
     PreferModernMathApis,
     restriction,
+    pending
 );
 
 impl Rule for PreferModernMathApis {
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 bab6f348c228d..448a2410526ba 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
@@ -46,7 +46,8 @@ declare_oxc_lint!(
     /// array.some(Boolean);
     /// ```
     PreferNativeCoercionFunctions,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferNativeCoercionFunctions {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_optional_catch_binding.rs b/crates/oxc_linter/src/rules/unicorn/prefer_optional_catch_binding.rs
index df55116919a71..3bc7ff458abb5 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_optional_catch_binding.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_optional_catch_binding.rs
@@ -38,7 +38,8 @@ declare_oxc_lint!(
     /// } catch { }
     /// ```
     PreferOptionalCatchBinding,
-    style
+    style,
+    pending
 );
 
 impl Rule for PreferOptionalCatchBinding {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_regexp_test.rs b/crates/oxc_linter/src/rules/unicorn/prefer_regexp_test.rs
index e53e07b4266a3..21ec2d73e5ec1 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_regexp_test.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_regexp_test.rs
@@ -39,7 +39,8 @@ declare_oxc_lint!(
     ///
     /// ```
     PreferRegexpTest,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferRegexpTest {
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 d784ee12f5c56..5ea52afdc5f56 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_set_size.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_set_size.rs
@@ -37,7 +37,8 @@ declare_oxc_lint!(
     ///
     /// ```
     PreferSetSize,
-    correctness
+    correctness,
+    pending
 );
 
 impl Rule for PreferSetSize {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_string_slice.rs b/crates/oxc_linter/src/rules/unicorn/prefer_string_slice.rs
index da9377d8636d6..3acea52d41643 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_string_slice.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_string_slice.rs
@@ -25,7 +25,8 @@ declare_oxc_lint!(
     /// ```javascript
     /// ```
     PreferStringSlice,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferStringSlice {
diff --git a/crates/oxc_linter/src/rules/unicorn/prefer_type_error.rs b/crates/oxc_linter/src/rules/unicorn/prefer_type_error.rs
index ca4408e2ed08b..a4edd660e1340 100644
--- a/crates/oxc_linter/src/rules/unicorn/prefer_type_error.rs
+++ b/crates/oxc_linter/src/rules/unicorn/prefer_type_error.rs
@@ -42,7 +42,8 @@ declare_oxc_lint!(
     /// }
     /// ```
     PreferTypeError,
-    pedantic
+    pedantic,
+    pending
 );
 
 impl Rule for PreferTypeError {
diff --git a/crates/oxc_linter/src/rules/unicorn/require_array_join_separator.rs b/crates/oxc_linter/src/rules/unicorn/require_array_join_separator.rs
index 7dde15d707241..eb380149b6817 100644
--- a/crates/oxc_linter/src/rules/unicorn/require_array_join_separator.rs
+++ b/crates/oxc_linter/src/rules/unicorn/require_array_join_separator.rs
@@ -36,7 +36,8 @@ declare_oxc_lint!(
     /// foo.join(",")
     /// ```
     RequireArrayJoinSeparator,
-    style
+    style,
+    pending
 );
 
 fn is_array_prototype_property(member_expr: &MemberExpression, property: &str) -> bool {
diff --git a/crates/oxc_linter/src/rules/unicorn/text_encoding_identifier_case.rs b/crates/oxc_linter/src/rules/unicorn/text_encoding_identifier_case.rs
index 11a7cc22d1170..b1a4c3c6a7675 100644
--- a/crates/oxc_linter/src/rules/unicorn/text_encoding_identifier_case.rs
+++ b/crates/oxc_linter/src/rules/unicorn/text_encoding_identifier_case.rs
@@ -43,7 +43,8 @@ declare_oxc_lint!(
     ///
     /// ```
     TextEncodingIdentifierCase,
-    style
+    style,
+    pending
 );
 
 impl Rule for TextEncodingIdentifierCase {
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 50edb679616ea..166caa67b9bc5 100644
--- a/crates/oxc_linter/src/rules/unicorn/throw_new_error.rs
+++ b/crates/oxc_linter/src/rules/unicorn/throw_new_error.rs
@@ -47,7 +47,8 @@ declare_oxc_lint!(
     ///
     /// ```
     ThrowNewError,
-    style
+    style,
+    pending
 );
 
 impl Rule for ThrowNewError {