docs(linter): update rule documentation (#7684)

crates/oxc_linter/src/rules/jest/valid_expect.rs

@@ -56,18 +56,29 @@ impl Default for ValidExpectConfig {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// This rule triggers a warning if `expect()` is called with more than one argument
-    /// or without arguments. It would also issue a warning if there is nothing called
-    /// on `expect()`, e.g.:
+    /// Checks that `expect()` is called correctly.
+    ///
+    /// Why is this bad?
+    ///
+    /// `expect()` is a function that is used to assert values in tests. It should be called with a single argument, which is the value to be tested. If you call `expect()` with no arguments, or with more than one argument, it will not work as expected.
     ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// expect();
     /// expect('something');
     /// expect(true).toBeDefined;
     /// expect(Promise.resolve('Hi!')).resolves.toBe('Hi!');
     /// ```
     ///
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// expect('something').toEqual('something');
+    /// expect(true).toBeDefined();
+    /// expect(Promise.resolve('Hi!')).resolves.toBe('Hi!');
+    /// ```
+    ///
     /// This rule is compatible with [eslint-plugin-vitest](https://github.com/veritem/eslint-plugin-vitest/blob/v1.1.9/docs/rules/valid-expect.md),
     /// to use it, add the following configuration to your `.eslintrc.json`:
     ///

crates/oxc_linter/src/rules/jest/valid_title.rs

@@ -44,14 +44,21 @@ impl std::ops::Deref for ValidTitle {
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Checks that the title of Jest blocks are valid by ensuring that titles are:
+    /// Checks that the titles of Jest blocks are valid.
     ///
+    /// Titles must be:
     /// - not empty,
-    /// - is a string,
+    /// - strings,
     /// - not prefixed with their block name,
-    /// - have no leading or trailing spaces
+    /// - have no leading or trailing spaces.
+    ///
+    /// Why is this bad?
+    ///
+    /// Titles that are not valid can be misleading and make it harder to understand the purpose of the test.
     ///
     /// ### Example
+    ///
+    /// Examples of **incorrect** code for this rule:
     /// ```javascript
     /// describe('', () => {});
     /// describe('foo', () => {
@@ -63,6 +70,11 @@ declare_oxc_lint!(
     /// xit('', () => {});
     /// xtest('', () => {});
     /// ```
+    /// Examples of **correct** code for this rule:
+    /// ```javascript
+    /// describe('foo', () => {});
+    /// it('bar', () => {});
+    /// test('baz', () => {});
     ValidTitle,
     correctness,
     conditional_fix

crates/oxc_linter/src/rules/jsx_a11y/iframe_has_title.rs

@@ -27,7 +27,7 @@ declare_oxc_lint!(
     ///
     /// Enforce iframe elements have a title attribute.
     ///
-    /// ### Why is this necessary?
+    /// ### Why is this bad?
     ///
     /// Screen reader users rely on a iframe title to describe the contents of the iframe.
     /// Navigating through iframe and iframe elements quickly becomes difficult and confusing for users of this technology if the markup does not contain a title attribute.

crates/oxc_linter/src/rules/react/no_children_prop.rs

@@ -25,10 +25,12 @@ pub struct NoChildrenProp;
 declare_oxc_lint!(
     /// ### What it does
     ///
-    /// Children should always be actual children, not passed in as a prop.
+    /// Checks that children are not passed using a prop.
     ///
-    /// When using JSX, the children should be nested between the opening and closing tags.
+    /// Why is this bad?
     ///
+    /// Children should always be actual children, not passed in as a prop.
+    /// When using JSX, the children should be nested between the opening and closing tags.
     /// When not using JSX, the children should be passed as additional arguments to `React.createElement`.
     ///
     /// ### Example