From f029090d65d508d98ba01548e567d9e26f92000c Mon Sep 17 00:00:00 2001
From: camc314 <18101008+camc314@users.noreply.github.com>
Date: Thu, 5 Dec 2024 16:17:46 +0000
Subject: [PATCH] docs(linter): update rule documentation (#7684)

---
 .../oxc_linter/src/rules/jest/valid_expect.rs  | 17 ++++++++++++++---
 .../oxc_linter/src/rules/jest/valid_title.rs   | 18 +++++++++++++++---
 .../src/rules/jsx_a11y/iframe_has_title.rs     |  2 +-
 .../src/rules/react/no_children_prop.rs        |  6 ++++--
 4 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/crates/oxc_linter/src/rules/jest/valid_expect.rs b/crates/oxc_linter/src/rules/jest/valid_expect.rs
index 765aa9c220724..0976b661ce544 100644
--- a/crates/oxc_linter/src/rules/jest/valid_expect.rs
+++ b/crates/oxc_linter/src/rules/jest/valid_expect.rs
@@ -56,11 +56,15 @@ 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');
@@ -68,6 +72,13 @@ declare_oxc_lint!(
     /// 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`:
     ///
diff --git a/crates/oxc_linter/src/rules/jest/valid_title.rs b/crates/oxc_linter/src/rules/jest/valid_title.rs
index f3d354b4b8355..b86418078fdea 100644
--- a/crates/oxc_linter/src/rules/jest/valid_title.rs
+++ b/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
diff --git a/crates/oxc_linter/src/rules/jsx_a11y/iframe_has_title.rs b/crates/oxc_linter/src/rules/jsx_a11y/iframe_has_title.rs
index f436e04261e2e..244d40902b2ce 100644
--- a/crates/oxc_linter/src/rules/jsx_a11y/iframe_has_title.rs
+++ b/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.
diff --git a/crates/oxc_linter/src/rules/react/no_children_prop.rs b/crates/oxc_linter/src/rules/react/no_children_prop.rs
index 91cbe05ae3a01..c9986544d2687 100644
--- a/crates/oxc_linter/src/rules/react/no_children_prop.rs
+++ b/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