docs(linter): improve docs for promise rules (#6051)

crates/oxc_linter/src/rules/promise/avoid_new.rs

@@ -22,7 +22,7 @@ declare_oxc_lint!(
     /// Many cases that use `new Promise()` could be refactored to use an
     /// `async` function. `async` is considered more idiomatic in modern JavaScript.
     ///
-    /// ### Example
+    /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript

crates/oxc_linter/src/rules/promise/catch_or_return.rs

@@ -60,7 +60,7 @@ declare_oxc_lint!(
     /// promise rejections can cause your application to crash.
     ///
     ///
-    /// ### Example
+    /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript

crates/oxc_linter/src/rules/promise/no_new_statics.rs

@@ -26,7 +26,7 @@ declare_oxc_lint!(
     /// Calling a static `Promise` method with `new` is invalid and will result
     /// in a `TypeError` at runtime.
     ///
-    /// ### Example
+    /// ### Examples
     ///
     /// Examples of **incorrect** code for this rule:
     /// ```javascript

crates/oxc_linter/src/rules/promise/no_return_in_finally.rs

@@ -28,12 +28,19 @@ declare_oxc_lint!(
     /// Disallow return statements inside a callback passed to finally(), since nothing would
     /// consume what's returned.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// myPromise.finally(function (val) {
     ///   return val
     /// })
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// Promise.resolve(1).finally(() => { console.log(2) })
+    /// ```
     NoReturnInFinally,
     nursery,
 );

crates/oxc_linter/src/rules/promise/param_names.rs

@@ -50,11 +50,18 @@ declare_oxc_lint!(
     /// RevealingConstructor pattern. Using the same parameter names as the language specification
     /// makes code more uniform and easier to understand.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// new Promise(function (reject, resolve) { /* ... */ }) // incorrect order
     /// new Promise(function (ok, fail) { /* ... */ }) // non-standard parameter names
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// new Promise(function(resolve, reject) {})
+    /// ```
     ParamNames,
     style,
 );

crates/oxc_linter/src/rules/promise/prefer_await_to_then.rs

@@ -21,9 +21,16 @@ declare_oxc_lint!(
     ///
     /// Async/await syntax can be seen as more readable.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
+    /// function foo() { hey.then(x => {}) }
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
     /// ```javascript
-    /// myPromise.then(doSomething)
+    /// async function hi() { await thing() }
     /// ```
     PreferAwaitToThen,
     style,

crates/oxc_linter/src/rules/promise/valid_params.rs

@@ -51,10 +51,17 @@ declare_oxc_lint!(
     /// Calling a Promise function with the incorrect number of arguments can lead to unexpected
     /// behavior or hard to spot bugs.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// Promise.resolve(1, 2)
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// Promise.resolve(1)
+    /// ```
     ValidParams,
     correctness,
 );