docs(linter): update docs Examples for linter rules (#5513)

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

@@ -24,10 +24,10 @@ declare_oxc_lint!(
     ///
     /// Private class members that are declared and not used anywhere in the code are most likely an error due to incomplete refactoring. Such class members take up space in the code and can lead to confusion by readers.
     ///
-    /// ### Example
-    /// ```javascript
+    /// ### Examples
     ///
-    /// /// bad
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
     /// class A {
     ///		#unusedMember = 5;
     ///	}
@@ -54,15 +54,17 @@ declare_oxc_lint!(
     ///			get #unusedAccessor() {}
     ///			set #unusedAccessor(value) {}
     ///	}
+    /// ```
     ///
-    /// /// Good
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
     /// class A {
     ///		#usedMember = 42;
     ///		method() {
     ///				return this.#usedMember;
     ///		}
     ///	}
-
+    ///
     ///	class B {
     ///			#usedMethod() {
     ///					return 42;
@@ -71,7 +73,7 @@ declare_oxc_lint!(
     ///					return this.#usedMethod();
     ///			}
     ///	}
-
+    ///
     ///	class C {
     ///			get #usedAccessor() {}
     ///			set #usedAccessor(value) {}

crates/oxc_linter/src/rules/import/no_amd.rs

@@ -22,12 +22,18 @@ declare_oxc_lint!(
     ///
     /// Forbid AMD `require` and `define` calls.
     ///
-    /// ### Example
+    /// ### Why is this bad?
+    ///
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     ///
     /// ```javascript
-    /// // fail
     /// require([a, b], function() {} );
-    /// // pass
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
     /// require('../name');
     /// require(`../name`);
     /// ```

crates/oxc_linter/src/rules/import/no_default_export.rs

@@ -18,23 +18,20 @@ declare_oxc_lint!(
     ///
     /// ### Examples
     ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// // bad1.js
-    ///
-    /// // There is a default export.
-    /// export const foo = 'foo';
-    /// const bar = 'bar';
     /// export default 'bar';
-    /// ```
-    ///
-    /// ```javascript
-    /// // bad2.js
     ///
-    /// // There is a default export.
     /// const foo = 'foo';
     /// export { foo as default }
     /// ```
     ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// export const foo = 'foo';
+    /// export const bar = 'bar';
+    /// ```
+    ///
     NoDefaultExport,
     restriction
 );

crates/oxc_linter/src/rules/jsdoc/check_access.rs

@@ -25,6 +25,7 @@ pub struct CheckAccess;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Checks that `@access` tags use one of the following values:
     /// - "package", "private", "protected", "public"
     ///
@@ -33,20 +34,24 @@ declare_oxc_lint!(
     /// - Use of multiple instances of `@access` (or the `@public`, etc) on the same doc block.
     ///
     /// ### Why is this bad?
-    /// It is important to have a consistent way of specifying access levels.
     ///
-    /// ### Example
-    /// ```javascript
-    /// // Passing
-    /// /** @access private */
+    /// It is important to have a consistent way of specifying access levels.
     ///
-    /// /** @private */
+    /// ### Examples
     ///
-    /// // Failing
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
     /// /** @access private @public */
     ///
     /// /** @access invalidlevel */
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// /** @access private */
+    ///
+    /// /** @private */
+    /// ```
     CheckAccess,
     restriction
 );

crates/oxc_linter/src/rules/jsdoc/check_property_names.rs

@@ -20,33 +20,39 @@ pub struct CheckPropertyNames;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Ensures that property names in JSDoc are not duplicated on the same block and that nested properties have defined roots.
     ///
     /// ### Why is this bad?
+    ///
     /// `@property` tags with the same name can be confusing and may indicate a mistake.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// // Passing
     /// /**
     ///  * @typedef {object} state
     ///  * @property {number} foo
+    ///  * @property {string} foo
     ///  */
+    ///
     /// /**
     ///  * @typedef {object} state
-    ///  * @property {object} foo
     ///  * @property {number} foo.bar
     ///  */
+    /// ```
     ///
-    /// // Failing
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
     /// /**
     ///  * @typedef {object} state
     ///  * @property {number} foo
-    ///  * @property {string} foo
     ///  */
     ///
     /// /**
     ///  * @typedef {object} state
+    ///  * @property {object} foo
     ///  * @property {number} foo.bar
     ///  */
     /// ```

crates/oxc_linter/src/rules/jsdoc/check_tag_names.rs

@@ -19,18 +19,18 @@ pub struct CheckTagNames(Box<CheckTagnamesConfig>);
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Reports invalid block tag names.
     /// Additionally checks for tag names that are redundant when using a type checker such as TypeScript.
     ///
     /// ### Why is this bad?
+    ///
     /// Using invalid tags can lead to confusion and make the documentation harder to read.
     ///
-    /// ### Example
-    /// ```javascript
-    /// // Passing
-    /// /** @param */
+    /// ### Examples
     ///
-    /// // Failing
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
     /// /** @Param */
     /// /** @foo */
     ///
@@ -39,6 +39,11 @@ declare_oxc_lint!(
     ///  * @type {string}
     ///  */
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// /** @param */
+    /// ```
     CheckTagNames,
     correctness
 );

crates/oxc_linter/src/rules/jsdoc/empty_tags.rs

@@ -17,6 +17,7 @@ pub struct EmptyTags(Box<EmptyTagsConfig>);
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Expects the following tags to be empty of any content:
     /// - `@abstract`
     /// - `@async`
@@ -38,20 +39,24 @@ declare_oxc_lint!(
     /// - `@static`
     ///
     /// ### Why is this bad?
-    /// The void tags should be empty.
     ///
-    /// ### Example
-    /// ```javascript
-    /// // Passing
-    /// /** @async */
+    /// The void tags should be empty.
     ///
-    /// /** @private */
+    /// ### Examples
     ///
-    /// // Failing
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
     /// /** @async foo */
     ///
     /// /** @private bar */
     /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// /** @async */
+    ///
+    /// /** @private */
+    /// ```
     EmptyTags,
     restriction
 );

crates/oxc_linter/src/rules/jsdoc/implements_on_classes.rs

@@ -22,15 +22,26 @@ pub struct ImplementsOnClasses;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Reports an issue with any non-constructor function using `@implements`.
     ///
     /// ### Why is this bad?
+    ///
     /// Constructor functions should be
     /// whether marked with `@class`, `@constructs`, or being an ES6 class constructor.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
+    /// ```javascript
+    /// /**
+    ///  * @implements {SomeClass}
+    ///  */
+    /// function quux () {}
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
     /// ```javascript
-    /// // Passing
     /// class Foo {
     ///   /**
     ///    * @implements {SomeClass}
@@ -42,12 +53,6 @@ declare_oxc_lint!(
     ///  * @class
     ///  */
     /// function quux () {}
-    ///
-    /// // Failing
-    /// /**
-    ///  * @implements {SomeClass}
-    ///  */
-    /// function quux () {}
     /// ```
     ImplementsOnClasses,
     correctness

crates/oxc_linter/src/rules/jsdoc/no_defaults.rs

@@ -20,23 +20,29 @@ pub struct NoDefaults(Box<NoDefaultsConfig>);
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// This rule reports defaults being used on the relevant portion of `@param` or `@default`.
     /// It also optionally reports the presence of the square-bracketed optional arguments at all.
     ///
     /// ### Why is this bad?
+    ///
     /// The rule is intended to prevent the indication of defaults on tags
     /// where this would be redundant with ES6 default parameters.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// // Passing
-    /// /** @param {number} foo */
+    /// /** @param {number} [foo="7"] */
     /// function quux (foo) {}
-    /// /** @param foo */
+    /// ```
+    ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// /** @param {number} foo */
     /// function quux (foo) {}
     ///
-    /// // Failing
-    /// /** @param {number} [foo="7"] */
+    /// /** @param foo */
     /// function quux (foo) {}
     /// ```
     NoDefaults,

crates/oxc_linter/src/rules/jsdoc/require_param.rs

@@ -23,20 +23,25 @@ pub struct RequireParam(Box<RequireParamConfig>);
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Requires that all function parameters are documented with JSDoc `@param` tags.
     ///
     /// ### Why is this bad?
+    ///
     /// The rule is aimed at enforcing code quality and maintainability by requiring that all function parameters are documented.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// // Passing
     /// /** @param foo */
-    /// function quux (foo) {}
+    /// function quux (foo, bar) {}
+    /// ```
     ///
-    /// // Failing
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
     /// /** @param foo */
-    /// function quux (foo, bar) {}
+    /// function quux (foo) {}
     /// ```
     RequireParam,
     pedantic,

crates/oxc_linter/src/rules/jsdoc/require_param_description.rs

@@ -24,19 +24,24 @@ pub struct RequireParamDescription;
 
 declare_oxc_lint!(
     /// ### What it does
+    ///
     /// Requires that each `@param` tag has a description value.
     ///
     /// ### Why is this bad?
+    ///
     /// The description of a param should be documented.
     ///
-    /// ### Example
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
-    /// // Passing
-    /// /** @param foo Foo. */
+    /// /** @param foo */
     /// function quux (foo) {}
+    /// ```
     ///
-    /// // Failing
-    /// /** @param foo */
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// /** @param foo Foo. */
     /// function quux (foo) {}
     /// ```
     RequireParamDescription,