From d6f71288765d3d18765d4b0ed1d50d602a9e901a Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 14:25:08 +1200
Subject: [PATCH 1/7] docs: use inclusive language

---
 README.md                        |  3 +-
 docs/rules/expect-expect.md      |  6 +--
 docs/rules/lowercase-name.md     | 10 ++--
 docs/rules/no-hooks.md           |  4 +-
 docs/rules/no-large-snapshots.md | 84 +++++++++++++++++---------------
 5 files changed, 57 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index ed5c4f158..c708a4254 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,8 @@ Then configure the rules you want to use under the rules section.
 }
 ```
 
-You can also whitelist the environment variables provided by Jest by doing:
+You can also tell ESLint about the environment variables provided by Jest by
+doing:
 
 ```json
 {
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index af61b1ec8..0aeec4119 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -42,9 +42,9 @@ it('should work with callbacks/async', () => {
 
 ### `assertFunctionNames`
 
-This array option whitelists the assertion function names to look for. Function
-names can use wildcards like `request.*.expect`, `request.**.expect`,
-`request.*.expect*`
+This array option specifies the names of functions that should be considered to
+be asserting functions. Function names can use wildcards i.e `request.*.expect`,
+`request.**.expect`, `request.*.expect*`
 
 Examples of **incorrect** code for the `{ "assertFunctionNames": ["expect"] }`
 option:
diff --git a/docs/rules/lowercase-name.md b/docs/rules/lowercase-name.md
index 9108e4321..3666cb6c6 100644
--- a/docs/rules/lowercase-name.md
+++ b/docs/rules/lowercase-name.md
@@ -37,8 +37,8 @@ it('adds 1 + 2 to equal 3', () => {
 
 ### `ignore`
 
-This array option whitelists function names so that this rule does not report
-their usage as being incorrect. There are three possible values:
+This array option controls which Jest functions are checked by this rule. There
+are three possible values:
 
 - `"describe"`
 - `"test"`
@@ -73,9 +73,9 @@ it('Uppercase description');
 
 ### `allowedPrefixes`
 
-This array option whitelists prefixes that titles can start with with capitals.
-This can be useful when writing tests for api endpoints, where you'd like to
-prefix with the HTTP method.
+This array option allows specifying prefixes which contain capitals that titles
+can start with. This can be useful when writing tests for api endpoints, where
+you'd like to prefix with the HTTP method.
 
 By default, nothing is allowed (the equivalent of `{ "allowedPrefixes": [] }`).
 
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 1b037db83..597926162 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -101,8 +101,8 @@ describe('foo', () => {
 
 ### `allow`
 
-This array option whitelists setup and teardown hooks so that this rule does not
-report their usage as being incorrect. There are four possible values:
+This array option controls which Jest hooks are checked by this rule. There are
+four possible values:
 
 - `"beforeAll"`
 - `"beforeEach"`
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index f6f075154..b8d942065 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,10 +1,10 @@
 # disallow large snapshots (`no-large-snapshots`)
 
 When using Jest's snapshot capability one should be mindful of the size of
-created snapshots. As a best practice snapshots should be limited in size in
-order to be more manageable and reviewable. A stored snapshot is only as good as
-its review and as such keeping it short, sweet, and readable is important to
-allow for thorough reviews.
+created snapshots. As a general best practice snapshots should be limited in
+size in order to be more manageable and reviewable. A stored snapshot is only as
+good as its review and as such keeping it short, sweet, and readable is
+important to allow for thorough reviews.
 
 ## Usage
 
@@ -15,9 +15,11 @@ you should set `parserOptions` in your config to at least allow ES2015 in order
 to use this rule:
 
 ```js
-parserOptions: {
-  ecmaVersion: 2015,
-},
+module.exports = {
+  parserOptions: {
+    ecmaVersion: 2015,
+  },
+};
 ```
 
 ## Rule Details
@@ -119,48 +121,52 @@ size and `maxSize` for
 If only `maxSize` is provided on options, the value of `maxSize` will be used to
 both snapshot types (Inline and External).
 
-In addition there is an option for whitelisting large snapshot files. Since
-`//eslint` comments will be removed when a `.snap` file is updated, this option
-provides a way of whitelisting large snapshots. The list of whitelistedSnapshots
-is keyed first on the absolute filepath of the snapshot file. You can then
-provide an array of strings to match the snapshot names against. If you're using
-a `.eslintrc.js` file, you can use regular expressions AND strings.
+Since `eslint-disable` comments are not preserved by Jest when updating
+snapshots, you can use the `whitelistedSnapshots` option to have specific
+snapshots allowed regardless of their size.
+
+This option takes a map, with the key being the absolute filepath to a snapshot
+file, and the value an array of values made up of strings and regular
+expressions to compare to the names of the snapshots in the `.snap` file when
+checking if the snapshots size should be allowed.
+
+Note that regular expressions can only be passed in via `.eslintrc.js` as
+instances of `RegExp`.
 
 In an `.eslintrc.js` file:
 
 ```javascript
-...
-
-  "rules": {
-    "jest/no-large-snapshots": ["error",
+module.exports = {
+  rules: {
+    'jest/no-large-snapshots': [
+      'error',
       {
-        "whitelistedSnapshots": {
-          "/path/to/file.js.snap": ["snapshot name 1", /a big snapshot \d+/]
-        }
-      }]
-  }
-
-...
+        whitelistedSnapshots: {
+          '/path/to/file.js.snap': ['snapshot name 1', /a big snapshot \d+/],
+        },
+      },
+    ],
+  },
+};
 ```
 
-Note: If you store your paths as relative paths, you can use `path.resolve` so
-that it can be shared between computers. For example, suppose you have your
-whitelisted snapshots in a file called `allowed-snaps.js` which stores them as
-relative paths. To convert them to absolute paths you can do something like the
-following:
+Since absolute paths are typically not very portable, you can use the builtin
+`path.resolve` function to expand relative paths into absolutes like so:
 
 ```javascript
 const path = require('path');
-const {mapKeys} = require('lodash');
-
-
-const allowedSnapshots = require('./allowed-snaps.js');
-const whitelistedSnapshots = mapKeys(allowedSnapshots, (val, file) => path.resolve(__dirname, file));
 
-...
+module.exports = {
   rules: {
-    "jest/no-large-snapshots": ["error",
-      { whitelistedSnapshots }
-    ]
-  }
+    'jest/no-large-snapshots': [
+      'error',
+      {
+        whitelistedSnapshots: {
+          [path.resolve('test/__snapshots__/get.js.snap')]: ['full request'],
+          [path.resolve('test/__snapshots__/put.js.snap')]: ['full request'],
+        },
+      },
+    ],
+  },
+};
 ```

From e2210a422fea4ee5bb916b18820321fbe32f4764 Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 14:52:19 +1200
Subject: [PATCH 2/7] chore: refactor `generate-rules-table` into
 `regenerate-docs` tool

---
 package.json                                  |  2 +-
 ...rate-rules-table.ts => regenerate-docs.ts} | 36 ++++++++++++++-----
 2 files changed, 28 insertions(+), 10 deletions(-)
 rename tools/{generate-rules-table.ts => regenerate-docs.ts} (78%)

diff --git a/package.json b/package.json
index 1f32cc8c1..959a541c9 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,7 @@
     "prepack": "yarn build",
     "prettylint": "prettylint docs/**/*.md README.md package.json",
     "test": "jest",
-    "tools:generate-rules-table": "ts-node -T tools/generate-rules-table",
+    "tools:regenerate-docs": "ts-node -T tools/regenerate-docs",
     "typecheck": "tsc -p ."
   },
   "husky": {
diff --git a/tools/generate-rules-table.ts b/tools/regenerate-docs.ts
similarity index 78%
rename from tools/generate-rules-table.ts
rename to tools/regenerate-docs.ts
index eb9b33186..be78f8aa8 100644
--- a/tools/generate-rules-table.ts
+++ b/tools/regenerate-docs.ts
@@ -3,9 +3,19 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { TSESLint } from '@typescript-eslint/experimental-utils';
-import prettier from 'prettier';
+import prettier, { Options } from 'prettier';
+import { prettier as prettierRC } from '../package.json';
 import config from '../src/index';
 
+const pathTo = {
+  readme: path.resolve(__dirname, '../README.md'),
+  rules: path.resolve(__dirname, '../src/rules'),
+  docs: path.resolve(__dirname, '../docs'),
+};
+
+const format = (str: string): string =>
+  prettier.format(str, { ...(prettierRC as Options), parser: 'markdown' });
+
 type FixType = 'fixable' | 'suggest';
 
 interface RuleDetails {
@@ -84,10 +94,7 @@ const importDefault = (moduleName: string) =>
   interopRequireDefault(require(moduleName)).default;
 
 const requireJestRule = (name: string): RuleModule =>
-  importDefault(
-    `../src/rules/${name}`,
-    // path.join('..', 'src', 'rules', name),
-  ) as RuleModule;
+  importDefault(path.join(pathTo.rules, name)) as RuleModule;
 
 const details: RuleDetails[] = Object.keys(config.configs.all.rules)
   .map(name => name.split('/')[1])
@@ -108,10 +115,21 @@ const details: RuleDetails[] = Object.keys(config.configs.all.rules)
     }),
   );
 
-let readme = fs.readFileSync(path.resolve(__dirname, '../README.md'), 'utf8');
+details.forEach(({ name, description }) => {
+  const pathToDoc = path.join(pathTo.docs, 'rules', `${name}.md`);
 
-readme = updateRulesList(details, readme);
+  const contents = fs
+    .readFileSync(pathToDoc)
+    .toString()
+    .split('\n');
 
-readme = prettier.format(readme, { parser: 'markdown' });
+  contents[0] = `# ${description} (\`${name}\`)`;
+
+  fs.writeFileSync(pathToDoc, format(contents.join('\n')));
+});
+
+let readme = fs.readFileSync(pathTo.readme, 'utf8');
+
+readme = updateRulesList(details, readme);
 
-fs.writeFileSync(path.resolve(__dirname, '../README.md'), readme, 'utf8');
+fs.writeFileSync(pathTo.readme, format(readme), 'utf8');

From 279d6c1c00cf5cfd879e6082b22f3c2d693e0a3c Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 15:06:28 +1200
Subject: [PATCH 3/7] ci: check that docs don't need to be regenerated

---
 .github/workflows/lint.yml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index a23bdef05..232a241c3 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -13,6 +13,24 @@ jobs:
           configFile: './package.json'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v2.1.0
+        with:
+          node-version: 12.x
+      - name: install
+        run: yarn
+      - name: regenerate docs
+        run: yarn tools:regenerate-docs
+      - name: report regenerated docs
+        run: |
+          git diff --name-only \
+            | xargs -I '{}' bash -c \
+              'echo "::error file={}::This needs to be regenerated by running \`tools:regenerate-docs\`" && false'
   danger:
     runs-on: ubuntu-latest
     steps:

From e4dc54287aa887756c990a7dba853281b4ed4038 Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 21:36:58 +1200
Subject: [PATCH 4/7] docs: improve rule descriptions

---
 README.md                                | 14 +++++------
 docs/rules/no-alias-methods.md           |  2 +-
 docs/rules/no-export.md                  |  2 +-
 docs/rules/no-standalone-expect.md       |  2 +-
 docs/rules/prefer-called-with.md         |  2 +-
 docs/rules/prefer-hooks-on-top.md        | 32 ++++++++++++------------
 docs/rules/require-top-level-describe.md |  2 +-
 docs/rules/valid-title.md                |  2 +-
 src/rules/no-export.ts                   |  2 +-
 src/rules/no-mocks-import.ts             |  4 +--
 src/rules/no-standalone-expect.ts        |  2 +-
 src/rules/prefer-called-with.ts          |  2 +-
 src/rules/prefer-hooks-on-top.ts         |  2 +-
 src/rules/prefer-strict-equal.ts         |  2 +-
 src/rules/require-top-level-describe.ts  |  2 +-
 15 files changed, 37 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index c708a4254..5223b0cd6 100644
--- a/README.md
+++ b/README.md
@@ -139,7 +139,7 @@ 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][] |              |
@@ -147,24 +147,24 @@ installations requiring long-term consistency.
 | [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][] |              |
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index 91c5bf8e3..7f373d5fe 100644
--- a/docs/rules/no-alias-methods.md
+++ b/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
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index 1f64c5db8..adab78f5f 100644
--- a/docs/rules/no-export.md
+++ b/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.
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index eff440a60..ccfbac804 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/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
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index a62035109..09bf7360c 100644
--- a/docs/rules/prefer-called-with.md
+++ b/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
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index e9c05cdda..47b9e7514 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/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();
     });
   });
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 69c0ffa21..a7b3a27dd 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/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
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index bb3ab76e8..1059e7c7f 100644
--- a/docs/rules/valid-title.md
+++ b/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:
 
diff --git a/src/rules/no-export.ts b/src/rules/no-export.ts
index 5edb4be4e..7547c4bc3 100644
--- a/src/rules/no-export.ts
+++ b/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: {
diff --git a/src/rules/no-mocks-import.ts b/src/rules/no-mocks-import.ts
index 53d973448..40d2856c6 100644
--- a/src/rules/no-mocks-import.ts
+++ b/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: [],
   },
diff --git a/src/rules/no-standalone-expect.ts b/src/rules/no-standalone-expect.ts
index 98fc79d66..bfe273465 100644
--- a/src/rules/no-standalone-expect.ts
+++ b/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: {
diff --git a/src/rules/prefer-called-with.ts b/src/rules/prefer-called-with.ts
index f907cba40..70e207f6e 100644
--- a/src/rules/prefer-called-with.ts
+++ b/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: {
diff --git a/src/rules/prefer-hooks-on-top.ts b/src/rules/prefer-hooks-on-top.ts
index f1507bb49..5d1e0ae61 100644
--- a/src/rules/prefer-hooks-on-top.ts
+++ b/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: {
diff --git a/src/rules/prefer-strict-equal.ts b/src/rules/prefer-strict-equal.ts
index a9e41ef9a..559cd990b 100644
--- a/src/rules/prefer-strict-equal.ts
+++ b/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,
     },
diff --git a/src/rules/require-top-level-describe.ts b/src/rules/require-top-level-describe.ts
index dfee7f276..339fd81d1 100644
--- a/src/rules/require-top-level-describe.ts
+++ b/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: {

From 9c67956c7bbc7a0b5ca380e5365e43adda174d79 Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 21:55:14 +1200
Subject: [PATCH 5/7] docs: ensure all code blocks contain valid code

---
 docs/rules/consistent-test-it.md       | 20 +++++-----
 docs/rules/expect-expect.md            |  8 ++--
 docs/rules/no-large-snapshots.md       |  4 +-
 docs/rules/prefer-expect-assertions.md | 10 ++---
 docs/rules/require-to-throw-message.md | 20 ++++++----
 docs/rules/valid-expect.md             | 52 ++++++++++++++------------
 6 files changed, 61 insertions(+), 53 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 5ea70eb1d..f58d58394 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -12,18 +12,18 @@ This rule gives you control over the usage of these keywords in your codebase.
 
 This rule can be configured as follows
 
-```js
+```json5
 {
-    type: 'object',
-    properties: {
-        fn: {
-            enum: ['it', 'test'],
-        },
-        withinDescribe: {
-            enum: ['it', 'test'],
-        },
+  type: 'object',
+  properties: {
+    fn: {
+      enum: ['it', 'test'],
+    },
+    withinDescribe: {
+      enum: ['it', 'test'],
     },
-    additionalProperties: false,
+  },
+  additionalProperties: false,
 }
 ```
 
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index 0aeec4119..54acd8e8d 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -55,11 +55,11 @@ option:
 import { expectSaga } from 'redux-saga-test-plan';
 import { addSaga } from '../src/sagas';
 
-test('returns sum', () =>
+test('returns sum', () => {
   expectSaga(addSaga, 1, 1)
     .returns(2)
     .run();
-);
+});
 ```
 
 Examples of **correct** code for the
@@ -71,11 +71,11 @@ Examples of **correct** code for the
 import { expectSaga } from 'redux-saga-test-plan';
 import { addSaga } from '../src/sagas';
 
-test('returns sum', () =>
+test('returns sum', () => {
   expectSaga(addSaga, 1, 1)
     .returns(2)
     .run();
-);
+});
 ```
 
 Examples of **correct** code for working with the HTTP assertions library
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index b8d942065..a83aefec9 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -106,11 +106,11 @@ snapshot:
 In an `eslintrc` file:
 
 ```json
-...
+{
   "rules": {
     "jest/no-large-snapshots": ["warn", { "maxSize": 12, "inlineMaxSize": 6 }]
   }
-...
+}
 ```
 
 Max number of lines allowed could be defined by snapshot type (Inline and
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index c46a8390c..d99720356 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -32,13 +32,13 @@ test('my test', () => {
 The following patterns are considered warnings:
 
 ```js
-test("my test", () => {
-  expect.assertions("1");
-  expect(someThing()).toEqual("foo");
+test('my test', () => {
+  expect.assertions('1');
+  expect(someThing()).toEqual('foo');
 });
 
-test("my test", () => {
-  expect.(someThing()).toEqual("foo");
+test('my test', () => {
+  expect(someThing()).toEqual('foo');
 });
 ```
 
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index 760f9020a..3245120ba 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -15,23 +15,27 @@ an error message.
 The following patterns are considered warnings:
 
 ```js
-expect(() => a()).toThrow();
+test('all the things', async () => {
+  expect(() => a()).toThrow();
 
-expect(() => a()).toThrowError();
+  expect(() => a()).toThrowError();
 
-await expect(a()).rejects.toThrow();
+  await expect(a()).rejects.toThrow();
 
-await expect(a()).rejects.toThrowError();
+  await expect(a()).rejects.toThrowError();
+});
 ```
 
 The following patterns are not considered warnings:
 
 ```js
-expect(() => a()).toThrow('a');
+test('all the things', async () => {
+  expect(() => a()).toThrow('a');
 
-expect(() => a()).toThrowError('a');
+  expect(() => a()).toThrowError('a');
 
-await expect(a()).rejects.toThrow('a');
+  await expect(a()).rejects.toThrow('a');
 
-await expect(a()).rejects.toThrowError('a');
+  await expect(a()).rejects.toThrowError('a');
+});
 ```
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index cb8512dd7..f69958784 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -95,33 +95,37 @@ supported by `expect`, such as
 The following patterns are considered warnings:
 
 ```js
-expect();
-expect().toEqual('something');
-expect('something', 'else');
-expect('something');
-await expect('something');
-expect(true).toBeDefined;
-expect(Promise.resolve('hello')).resolves;
-expect(Promise.resolve('hello')).resolves.toEqual('hello');
-Promise.resolve(expect(Promise.resolve('hello')).resolves.toEqual('hello'));
-Promise.all([
-  expect(Promise.resolve('hello')).resolves.toEqual('hello'),
-  expect(Promise.resolve('hi')).resolves.toEqual('hi'),
-]);
+test('all the things', async () => {
+  expect();
+  expect().toEqual('something');
+  expect('something', 'else');
+  expect('something');
+  await expect('something');
+  expect(true).toBeDefined;
+  expect(Promise.resolve('hello')).resolves;
+  expect(Promise.resolve('hello')).resolves.toEqual('hello');
+  Promise.resolve(expect(Promise.resolve('hello')).resolves.toEqual('hello'));
+  Promise.all([
+    expect(Promise.resolve('hello')).resolves.toEqual('hello'),
+    expect(Promise.resolve('hi')).resolves.toEqual('hi'),
+  ]);
+});
 ```
 
 The following patterns are not warnings:
 
 ```js
-expect('something').toEqual('something');
-expect([1, 2, 3]).toEqual([1, 2, 3]);
-expect(true).toBeDefined();
-await expect(Promise.resolve('hello')).resolves.toEqual('hello');
-await Promise.resolve(
-  expect(Promise.resolve('hello')).resolves.toEqual('hello'),
-);
-await Promise.all(
-  expect(Promise.resolve('hello')).resolves.toEqual('hello'),
-  expect(Promise.resolve('hi')).resolves.toEqual('hi'),
-);
+test('all the things', async () => {
+  expect('something').toEqual('something');
+  expect([1, 2, 3]).toEqual([1, 2, 3]);
+  expect(true).toBeDefined();
+  await expect(Promise.resolve('hello')).resolves.toEqual('hello');
+  await Promise.resolve(
+    expect(Promise.resolve('hello')).resolves.toEqual('hello'),
+  );
+  await Promise.all(
+    expect(Promise.resolve('hello')).resolves.toEqual('hello'),
+    expect(Promise.resolve('hi')).resolves.toEqual('hi'),
+  );
+});
 ```

From 7c0cf6c46fba5dddb670415581695d6408816f2e Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 21:57:48 +1200
Subject: [PATCH 6/7] docs: wrap references to code entities in code quotes

---
 docs/rules/consistent-test-it.md         | 4 ++--
 docs/rules/no-duplicate-hooks.md         | 2 +-
 docs/rules/require-top-level-describe.md | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index f58d58394..f8e4941a0 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -33,7 +33,7 @@ Decides whether to use `test` or `it`.
 
 #### withinDescribe
 
-Decides whether to use `test` or `it` within a describe scope.
+Decides whether to use `test` or `it` within a `describe` scope.
 
 ```js
 /*eslint jest/consistent-test-it: ["error", {"fn": "test"}]*/
@@ -72,7 +72,7 @@ describe('foo', function() {
 ### Default configuration
 
 The default configuration forces top level test to use `test` and all tests
-nested within describe to use `it`.
+nested within `describe` to use `it`.
 
 ```js
 /*eslint jest/consistent-test-it: ["error"]*/
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index adeb463ae..58b69d5dd 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,6 +1,6 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
-A describe block should not contain duplicate hooks.
+A `describe` block should not contain duplicate hooks.
 
 ## Rule Details
 
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index a7b3a27dd..2c2c4f946 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -9,7 +9,7 @@ in your test file.
 
 This rule triggers a warning if a test case (`test` and `it`) or a hook
 (`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
-top-level describe block.
+top-level `describe` block.
 
 The following patterns are considered warnings:
 

From 235c35e77354ac077de03d5ca9b5397d9f4dde1b Mon Sep 17 00:00:00 2001
From: Gareth Jones <jones258@gmail.com>
Date: Sun, 12 Jul 2020 22:01:59 +1200
Subject: [PATCH 7/7] docs: correct grammatical & spelling errors

---
 docs/rules/consistent-test-it.md         | 2 +-
 docs/rules/no-export.md                  | 5 ++---
 docs/rules/prefer-inline-snapshots.md    | 4 ++--
 docs/rules/prefer-to-be-null.md          | 2 +-
 docs/rules/prefer-to-be-undefined.md     | 2 +-
 docs/rules/prefer-to-have-length.md      | 4 ++--
 docs/rules/prefer-todo.md                | 2 +-
 docs/rules/require-to-throw-message.md   | 2 +-
 docs/rules/require-top-level-describe.md | 4 ++--
 docs/rules/valid-expect-in-promise.md    | 6 ++----
 10 files changed, 15 insertions(+), 18 deletions(-)

diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index f8e4941a0..d80f271e7 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -71,7 +71,7 @@ describe('foo', function() {
 
 ### Default configuration
 
-The default configuration forces top level test to use `test` and all tests
+The default configuration forces all top-level tests to use `test` and all tests
 nested within `describe` to use `it`.
 
 ```js
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index adab78f5f..c50bdd740 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,14 +1,13 @@
 # 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.
+Prevents using `exports` if a file has one or more tests in it.
 
 ## Rule Details
 
 This rule aims to eliminate duplicate runs of tests by exporting things from
 test files. If you import from a test file, then all the tests in that file will
 be run in each imported instance, so bottom line, don't export from a test, but
-instead move helper functions into a seperate file when they need to be shared
+instead move helper functions into a separate file when they need to be shared
 across tests.
 
 Examples of **incorrect** code for this rule:
diff --git a/docs/rules/prefer-inline-snapshots.md b/docs/rules/prefer-inline-snapshots.md
index f6c5998cf..e01308bf6 100644
--- a/docs/rules/prefer-inline-snapshots.md
+++ b/docs/rules/prefer-inline-snapshots.md
@@ -21,9 +21,9 @@ This rule has been deprecated in favor of
 
 ---
 
-In order to make snapshot tests more managable and reviewable
+In order to make snapshot tests more manageable and reviewable
 `toMatchInlineSnapshot()` and `toThrowErrorMatchingInlineSnapshot` should be
-used to write the snapshots inline in the test file.
+used to write the snapshots' inline in the test file.
 
 ## Rule details
 
diff --git a/docs/rules/prefer-to-be-null.md b/docs/rules/prefer-to-be-null.md
index 5bdbe525e..cf7b11f14 100644
--- a/docs/rules/prefer-to-be-null.md
+++ b/docs/rules/prefer-to-be-null.md
@@ -1,7 +1,7 @@
 # Suggest using `toBeNull()` (`prefer-to-be-null`)
 
 In order to have a better failure message, `toBeNull()` should be used upon
-asserting expections on null value.
+asserting expectations on null value.
 
 ## Rule details
 
diff --git a/docs/rules/prefer-to-be-undefined.md b/docs/rules/prefer-to-be-undefined.md
index e9ce8a903..bafc90f8c 100644
--- a/docs/rules/prefer-to-be-undefined.md
+++ b/docs/rules/prefer-to-be-undefined.md
@@ -1,7 +1,7 @@
 # Suggest using `toBeUndefined()` (`prefer-to-be-undefined`)
 
 In order to have a better failure message, `toBeUndefined()` should be used upon
-asserting expections on undefined value.
+asserting expectations on undefined value.
 
 ## Rule details
 
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index 4acfffaec..d44e9e079 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,12 +1,12 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
 In order to have a better failure message, `toHaveLength()` should be used upon
-asserting expectations on object's length property.
+asserting expectations on objects length property.
 
 ## Rule details
 
 This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
-used to assert object's length property.
+used to assert objects length property.
 
 ```js
 expect(files.length).toBe(1);
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 01ee8fda2..c294cbdbf 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -5,7 +5,7 @@ will be highlighted in the summary output.
 
 ## Rule details
 
-This rule triggers a warning if empty test case is used without 'test.todo'.
+This rule triggers a warning if empty test cases are used without 'test.todo'.
 
 ```js
 test('i need to write this test');
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index 3245120ba..4eea732f2 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,6 +1,6 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
-`toThrow()`, and its alias `toThrowError()`, are used to check if an error is
+`toThrow()` (and its alias `toThrowError()`) is used to check if an error is
 thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
 no message is defined, then the test will pass for any thrown error. Requiring a
 message ensures that the intended error is thrown.
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 2c2c4f946..7b314401e 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -2,8 +2,8 @@
 
 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
-files. This rule makes sure that you provide at least a top-level describe block
-in your test file.
+files. This rule makes sure you provide at least a top-level `describe` block in
+your test file.
 
 ## Rule Details
 
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index 89f90368d..e4f108adc 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -5,10 +5,8 @@ promise
 
 ## Rule details
 
-This rule triggers a warning if,
-
-- test is having assertions in `then` or `catch` block of a promise
-- and that promise is not returned from the test
+This rule looks for tests that have assertions in `then` and `catch` methods on
+promises that are not returned by the test.
 
 ### Default configuration