docs: use eslint-doc-generator for rule documentation (#1263)

jest-community · Nov 4, 2022 · b9faa0f · b9faa0f
1 parent ae6cfb7
commit b9faa0f
Show file tree

Hide file tree

Showing 63 changed files with 282 additions and 786 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -32,6 +32,10 @@ module.exports = {
     '@typescript-eslint/ban-types': 'error',
     '@typescript-eslint/no-unused-vars': 'error',
     'eslint-comments/no-unused-disable': 'error',
+    'eslint-plugin/require-meta-docs-description': [
+      'error',
+      { pattern: '^(Enforce|Require|Disallow|Suggest|Prefer)' },
+    ],
     'eslint-plugin/test-case-property-ordering': 'error',
     'no-else-return': 'error',
     'no-negated-condition': 'error',

diff --git a/README.md b/README.md
diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
@@ -1,14 +1,9 @@
-# Have control over `test` and `it` usages (`consistent-test-it`)
+# Enforce `test` and `it` usage conventions (`consistent-test-it`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
-🔧 This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Jest allows you to choose how you want to define your tests, using the `it` or
 the `test` keywords, with multiple permutations for each:
@@ -81,8 +76,6 @@ describe('foo', function () {
 });
 ```
 
-### Default configuration
-
 The default configuration forces all top-level tests to use `test` and all tests
 nested within `describe` to use `it`.
 

diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
@@ -1,10 +1,9 @@
 # Enforce assertion to be made in a test body (`expect-expect`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+⚠️ This rule _warns_ in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Ensure that there is at least one `expect` call made in a test.
 

diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
@@ -1,10 +1,6 @@
 # Enforces a maximum number assertion calls in a test body (`max-expects`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 As more assertions are made, there is a possible tendency for the test to be
 more likely to mix multiple objectives. To avoid this, this rule reports when

diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
@@ -1,10 +1,6 @@
 # Enforces a maximum depth to nested describe calls (`max-nested-describe`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 While it's useful to be able to group your tests together within the same file
 using `describe()`, having too many levels of nesting throughout your tests make

diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
@@ -1,17 +1,17 @@
 # Disallow alias methods (`no-alias-methods`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼⚠️ This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+This rule _warns_ in the 🎨 `style`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-🔧 This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 > These aliases are going to be removed in the next major version of Jest - see
-> https://github.com/facebook/jest/issues/13164 for more
+> <https://github.com/facebook/jest/issues/13164> for more
 
 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
@@ -24,8 +24,6 @@ method names used.
 This rule triggers a warning if the alias name, rather than the canonical name,
 of a method is used.
 
-### Default configuration
-
 The following patterns are considered warnings:
 
 ```js

diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
@@ -1,10 +1,9 @@
 # Disallow commented out tests (`no-commented-out-tests`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+⚠️ This rule _warns_ in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 This rule raises a warning about commented out tests. It's similar to
 no-disabled-tests rule.

diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
@@ -1,10 +1,9 @@
-# Prevent calling `expect` conditionally (`no-conditional-expect`)
+# Disallow calling `expect` conditionally (`no-conditional-expect`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 This rule prevents the use of `expect` in conditional blocks, such as `if`s &
 `catch`s.

diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
@@ -1,10 +1,6 @@
 # Disallow conditional logic in tests (`no-conditional-in-test`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Conditional logic in tests is usually an indication that a test is attempting to
 cover too much, and not testing the logic it intends to. Each branch of code

diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
@@ -1,14 +1,12 @@
 # Disallow use of deprecated functions (`no-deprecated-functions`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-🔧 This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Over the years Jest has accrued some debt in the form of functions that have
 either been renamed for clarity, or replaced with more powerful APIs.

diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
@@ -1,10 +1,9 @@
 # Disallow disabled tests (`no-disabled-tests`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+⚠️ This rule _warns_ in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Jest has a feature that allows you to temporarily mark tests as disabled. This
 feature is often helpful while debugging or to create placeholders for future

diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
@@ -1,14 +1,12 @@
-# Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
+# Disallow using a callback in asynchronous tests and hooks (`no-done-callback`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-💡 This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 When calling asynchronous code in hooks and tests, `jest` needs to know when the
 asynchronous work is complete to progress the current run.

diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
@@ -1,10 +1,6 @@
 # Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 A `describe` block should not contain duplicate hooks.
 

diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
@@ -1,10 +1,9 @@
 # Disallow using `exports` in files containing tests (`no-export`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Prevents using `exports` if a file has one or more tests in it.
 

diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
@@ -1,14 +1,12 @@
 # Disallow focused tests (`no-focused-tests`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-💡 This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 <!-- prettier-ignore -->
 Jest has a feature that allows you to focus tests by appending `.only` or

diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
@@ -1,10 +1,6 @@
 # Disallow setup and teardown hooks (`no-hooks`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Jest provides global functions for setup and teardown tasks, which are called
 before/after each test case and each test suite. The use of these hooks promotes

diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
@@ -1,10 +1,9 @@
 # Disallow identical titles (`no-identical-title`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Having identical titles for two different tests or test suites may create
 confusion. For example, when a test with the same title as another test in the

diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
@@ -1,9 +1,9 @@
 # Disallow conditional logic (`no-if`)
 
 ❌ This rule is deprecated. It was replaced by
-[no-conditional-in-test](no-conditional-in-test.md).
+[`no-conditional-in-test`](no-conditional-in-test.md).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Conditional logic in tests is usually an indication that a test is attempting to
 cover too much, and not testing the logic it intends to. Each branch of code

diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,10 +1,9 @@
 # Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 Prevents the use of string interpolations in snapshots.
 

diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
@@ -1,14 +1,12 @@
 # Disallow Jasmine globals (`no-jasmine-globals`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-🔧 This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 `jest` uses `jasmine` as a test runner. A side effect of this is that both a
 `jasmine` object, and some jasmine-specific globals, are exposed to the test
@@ -22,7 +20,7 @@ API.
 This rule reports on any usage of Jasmine globals, which is not ported to Jest,
 and suggests alternatives from Jest's own API.
 
-### Default configuration
+## Examples
 
 The following patterns are considered warnings:
 

diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
@@ -1,10 +1,6 @@
-# disallow large snapshots (`no-large-snapshots`)
+# Disallow large snapshots (`no-large-snapshots`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 When using Jest's snapshot capability one should be mindful of the size of
 created snapshots. As a general best practice snapshots should be limited in

diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
@@ -1,10 +1,9 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 When using `jest.mock`, your tests (just like the code being tested) should
 import from `./x`, not `./__mocks__/x`. Not following this rule can lead to

diff --git a/docs/rules/no-restricted-jest-methods.md b/docs/rules/no-restricted-jest-methods.md
@@ -1,10 +1,6 @@
 # Disallow specific `jest.` methods (`no-restricted-jest-methods`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 You may wish to restrict the use of specific `jest` methods.
 

diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
@@ -1,10 +1,6 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 You may want to ban specific matchers & modifiers from being used.
 

diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
@@ -1,10 +1,9 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
-💼 This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
 
-<!-- end rule header -->
+<!-- end auto-generated rule header -->
 
 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