docs: improve rule descriptions

README.md

@@ -139,32 +139,32 @@ installations requiring long-term consistency.
 | [no-deprecated-functions](docs/rules/no-deprecated-functions.md)       | Disallow use of deprecated functions                            |                  | ![fixable][] |
 | [no-disabled-tests](docs/rules/no-disabled-tests.md)                   | Disallow disabled tests                                         | ![recommended][] |              |
 | [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md)                 | Disallow duplicate setup and teardown hooks                     |                  |              |
-| [no-export](docs/rules/no-export.md)                                   | Prevent exporting from test files                               | ![recommended][] |              |
+| [no-export](docs/rules/no-export.md)                                   | Disallow using `exports` in files containing tests              | ![recommended][] |              |
 | [no-focused-tests](docs/rules/no-focused-tests.md)                     | Disallow focused tests                                          | ![recommended][] | ![fixable][] |
 | [no-hooks](docs/rules/no-hooks.md)                                     | Disallow setup and teardown hooks                               |                  |              |
 | [no-identical-title](docs/rules/no-identical-title.md)                 | Disallow identical titles                                       | ![recommended][] |              |
 | [no-if](docs/rules/no-if.md)                                           | Disallow conditional logic                                      |                  |              |
 | [no-jasmine-globals](docs/rules/no-jasmine-globals.md)                 | Disallow Jasmine globals                                        | ![recommended][] | ![fixable][] |
 | [no-jest-import](docs/rules/no-jest-import.md)                         | Disallow importing Jest                                         | ![recommended][] |              |
 | [no-large-snapshots](docs/rules/no-large-snapshots.md)                 | disallow large snapshots                                        |                  |              |
-| [no-mocks-import](docs/rules/no-mocks-import.md)                       | Disallow manually importing from **mocks**                      | ![recommended][] |              |
+| [no-mocks-import](docs/rules/no-mocks-import.md)                       | Disallow manually importing from `__mocks__`                    | ![recommended][] |              |
 | [no-restricted-matchers](docs/rules/no-restricted-matchers.md)         | Disallow specific matchers & modifiers                          |                  |              |
-| [no-standalone-expect](docs/rules/no-standalone-expect.md)             | Prevents expects that are outside of an it or test block.       | ![recommended][] |              |
+| [no-standalone-expect](docs/rules/no-standalone-expect.md)             | Disallow using `expect` outside of `it` or `test` blocks        | ![recommended][] |              |
 | [no-test-callback](docs/rules/no-test-callback.md)                     | Avoid using a callback in asynchronous tests                    | ![recommended][] | ![suggest][] |
 | [no-test-prefixes](docs/rules/no-test-prefixes.md)                     | Use `.only` and `.skip` over `f` and `x`                        | ![recommended][] | ![fixable][] |
 | [no-test-return-statement](docs/rules/no-test-return-statement.md)     | Disallow explicitly returning from tests                        |                  |              |
-| [prefer-called-with](docs/rules/prefer-called-with.md)                 | Suggest using `toBeCalledWith()` OR `toHaveBeenCalledWith()`    |                  |              |
+| [prefer-called-with](docs/rules/prefer-called-with.md)                 | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`    |                  |              |
 | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md)     | Suggest using `expect.assertions()` OR `expect.hasAssertions()` |                  | ![suggest][] |
-| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)               | Suggest to have all hooks at top level                          |                  |              |
+| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)               | Suggest having hooks before any test cases                      |                  |              |
 | [prefer-spy-on](docs/rules/prefer-spy-on.md)                           | Suggest using `jest.spyOn()`                                    |                  | ![fixable][] |
-| [prefer-strict-equal](docs/rules/prefer-strict-equal.md)               | Suggest using toStrictEqual()                                   |                  | ![suggest][] |
+| [prefer-strict-equal](docs/rules/prefer-strict-equal.md)               | Suggest using `toStrictEqual()`                                 |                  | ![suggest][] |
 | [prefer-to-be-null](docs/rules/prefer-to-be-null.md)                   | Suggest using `toBeNull()`                                      | ![style][]       | ![fixable][] |
 | [prefer-to-be-undefined](docs/rules/prefer-to-be-undefined.md)         | Suggest using `toBeUndefined()`                                 | ![style][]       | ![fixable][] |
 | [prefer-to-contain](docs/rules/prefer-to-contain.md)                   | Suggest using `toContain()`                                     | ![style][]       | ![fixable][] |
 | [prefer-to-have-length](docs/rules/prefer-to-have-length.md)           | Suggest using `toHaveLength()`                                  | ![style][]       | ![fixable][] |
 | [prefer-todo](docs/rules/prefer-todo.md)                               | Suggest using `test.todo`                                       |                  | ![fixable][] |
 | [require-to-throw-message](docs/rules/require-to-throw-message.md)     | Require a message for `toThrow()`                               |                  |              |
-| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Prevents test cases and hooks to be outside of a describe block |                  |              |
+| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block    |                  |              |
 | [valid-describe](docs/rules/valid-describe.md)                         | Enforce valid `describe()` callback                             | ![recommended][] |              |
 | [valid-expect](docs/rules/valid-expect.md)                             | Enforce valid `expect()` usage                                  | ![recommended][] |              |
 | [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md)       | Enforce having return statement when testing with promises      | ![recommended][] |              |

docs/rules/no-alias-methods.md

@@ -1,4 +1,4 @@
-# Don't use alias methods (`no-alias-methods`)
+# Disallow alias methods (`no-alias-methods`)
 
 Several Jest methods have alias names, such as `toThrow` having the alias of
 `toThrowError`. This rule ensures that only the canonical name as used in the

docs/rules/no-export.md

@@ -1,4 +1,4 @@
-# Prevent exporting from test files (`no-export`)
+# Disallow using `exports` in files containing tests (`no-export`)
 
 Prevents exports from test files. If a file has at least 1 test in it, then this
 rule will prevent exports.

docs/rules/no-standalone-expect.md

@@ -1,4 +1,4 @@
-# No standalone expect in a describe block (`no-standalone-expect`)
+# Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
 Prevents `expect` statements outside of a `test` or `it` block. An `expect`
 within a helper function (but outside of a `test` or `it` block) will not

docs/rules/prefer-called-with.md

@@ -1,4 +1,4 @@
-# Suggest using `toBeCalledWith` OR `toHaveBeenCalledWith` (`prefer-called-with`)
+# Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
 The `toBeCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion

docs/rules/prefer-hooks-on-top.md

@@ -1,4 +1,4 @@
-# Suggest to have all hooks at top-level before tests (`prefer-hooks-on-top`)
+# Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
 All hooks should be defined before the start of the tests
 
@@ -9,37 +9,37 @@ Examples of **incorrect** code for this rule
 ```js
 /* eslint jest/prefer-hooks-on-top: "error" */
 
-describe("foo" () => {
+describe('foo', () => {
   beforeEach(() => {
     //some hook code
   });
-  test("bar" () => {
+  test('bar', () => {
     some_fn();
   });
   beforeAll(() => {
     //some hook code
   });
-  test("bar" () => {
+  test('bar', () => {
     some_fn();
   });
 });
 
 // Nested describe scenario
-describe("foo" () => {
+describe('foo', () => {
   beforeAll(() => {
     //some hook code
   });
-  test("bar" () => {
+  test('bar', () => {
     some_fn();
   });
-  describe("inner_foo" () => {
+  describe('inner_foo', () => {
     beforeEach(() => {
       //some hook code
     });
-    test("inner bar" () => {
+    test('inner bar', () => {
       some_fn();
     });
-    test("inner bar" () => {
+    test('inner bar', () => {
       some_fn();
     });
     beforeAll(() => {
@@ -48,7 +48,7 @@ describe("foo" () => {
     afterAll(() => {
       //some hook code
     });
-    test("inner bar" () => {
+    test('inner bar', () => {
       some_fn();
     });
   });
@@ -60,7 +60,7 @@ Examples of **correct** code for this rule
 ```js
 /* eslint jest/prefer-hooks-on-top: "error" */
 
-describe("foo" () => {
+describe('foo', () => {
   beforeEach(() => {
     //some hook code
   });
@@ -71,24 +71,24 @@ describe("foo" () => {
   afterEach(() => {
     //some hook code
   });
-  test("bar" () => {
+  test('bar', () => {
     some_fn();
   });
 });
 
 // Nested describe scenario
-describe("foo" () => {
+describe('foo', () => {
   beforeEach(() => {
     //some hook code
   });
-  test("bar" () => {
+  test('bar', () => {
     some_fn();
   });
-  describe("inner_foo" () => {
+  describe('inner_foo', () => {
     beforeEach(() => {
       //some hook code
     });
-    test("inner bar" () => {
+    test('inner bar', () => {
       some_fn();
     });
   });

docs/rules/require-top-level-describe.md

@@ -1,4 +1,4 @@
-# Require top-level describe block (`require-top-level-describe`)
+# Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
 Jest allows you to organise your test files the way you want it. However, the
 more your codebase grows, the more it becomes hard to navigate in your test

docs/rules/valid-title.md

@@ -1,4 +1,4 @@
-# describe/test titles should be valid (`valid-title`)
+# Enforce valid titles (`valid-title`)
 
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 

src/rules/no-export.ts

@@ -9,7 +9,7 @@ export default createRule({
   meta: {
     docs: {
       category: 'Best Practices',
-      description: 'Prevent exporting from test files',
+      description: 'Disallow using `exports` in files containing tests',
       recommended: 'error',
     },
     messages: {

src/rules/no-mocks-import.ts

@@ -16,11 +16,11 @@ export default createRule({
     type: 'problem',
     docs: {
       category: 'Best Practices',
-      description: 'Disallow manually importing from __mocks__ ',
+      description: 'Disallow manually importing from `__mocks__`',
       recommended: 'error',
     },
     messages: {
-      noManualImport: `Mocks should not be manually imported from a ${mocksDirName} directory. Instead use jest.mock and import from the original module path.`,
+      noManualImport: `Mocks should not be manually imported from a ${mocksDirName} directory. Instead use \`jest.mock\` and import from the original module path.`,
     },
     schema: [],
   },

src/rules/no-standalone-expect.ts

@@ -65,7 +65,7 @@ export default createRule<
   meta: {
     docs: {
       category: 'Best Practices',
-      description: 'Prevents expects that are outside of an it or test block.',
+      description: 'Disallow using `expect` outside of `it` or `test` blocks',
       recommended: 'error',
     },
     messages: {

src/rules/prefer-called-with.ts

@@ -6,7 +6,7 @@ export default createRule({
     docs: {
       category: 'Best Practices',
       description:
-        'Suggest using `toBeCalledWith()` OR `toHaveBeenCalledWith()`',
+        'Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`',
       recommended: false,
     },
     messages: {

src/rules/prefer-hooks-on-top.ts

@@ -5,7 +5,7 @@ export default createRule({
   meta: {
     docs: {
       category: 'Best Practices',
-      description: 'Suggest to have all hooks at top level',
+      description: 'Suggest having hooks before any test cases',
       recommended: false,
     },
     messages: {

src/rules/prefer-strict-equal.ts

@@ -11,7 +11,7 @@ export default createRule({
   meta: {
     docs: {
       category: 'Best Practices',
-      description: 'Suggest using toStrictEqual()',
+      description: 'Suggest using `toStrictEqual()`',
       recommended: false,
       suggestion: true,
     },

src/rules/require-top-level-describe.ts

@@ -7,7 +7,7 @@ export default createRule({
     docs: {
       category: 'Best Practices',
       description:
-        'Prevents test cases and hooks to be outside of a describe block',
+        'Require test cases and hooks to be inside a `describe` block',
       recommended: false,
     },
     messages: {