docs: refactor jest.retryTimes() documentation (jestjs#13987)

docs/JestObjectAPI.md

@@ -1039,30 +1039,42 @@ Use the [`--showSeed`](CLI.md#--showseed) flag to print the seed in the test rep
 
 Returns `true` if test environment has been torn down.
 
-### `jest.retryTimes(numRetries, options)`
+### `jest.retryTimes(numRetries, options?)`
 
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. `options` are optional. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
-
-Example in a test:
+Runs failed tests n-times until they pass or until the max number of retries is exhausted.
 
 ```js
 jest.retryTimes(3);
+
 test('will fail', () => {
   expect(true).toBe(false);
 });
 ```
 
-If `logErrorsBeforeRetry` is enabled, Jest will log the error(s) that caused the test to fail to the console, providing visibility on why a retry occurred.
+If `logErrorsBeforeRetry` option is enabled, error(s) that caused the test to fail will be logged to the console.
 
 ```js
 jest.retryTimes(3, {logErrorsBeforeRetry: true});
+
 test('will fail', () => {
   expect(true).toBe(false);
 });
 ```
 
 Returns the `jest` object for chaining.
 
+:::caution
+
+`jest.retryTimes()` must be declared at the top level of a test file or in a `describe` block.
+
+:::
+
+:::info
+
+This function is only available with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner.
+
+:::
+
 ### `jest.setTimeout(timeout)`
 
 Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called.

website/versioned_docs/version-25.x/JestObjectAPI.md

@@ -660,6 +660,32 @@ Returns the number of fake timers still left to run.
 
 ## Misc
 
+### `jest.retryTimes(numRetries, options?)`
+
+Runs failed tests n-times until they pass or until the max number of retries is exhausted.
+
+```js
+jest.retryTimes(3);
+
+test('will fail', () => {
+  expect(true).toBe(false);
+});
+```
+
+Returns the `jest` object for chaining.
+
+:::caution
+
+`jest.retryTimes()` must be declared at the top level of a test file or in a `describe` block.
+
+:::
+
+:::info
+
+This function is only available with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner.
+
+:::
+
 ### `jest.setTimeout(timeout)`
 
 Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called.
@@ -675,18 +701,3 @@ Example:
 ```js
 jest.setTimeout(1000); // 1 second
 ```
-
-### `jest.retryTimes()`
-
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. This only works with [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus)!
-
-Example in a test:
-
-```js
-jest.retryTimes(3);
-test('will fail', () => {
-  expect(true).toBe(false);
-});
-```
-
-Returns the `jest` object for chaining.

website/versioned_docs/version-26.x/JestObjectAPI.md

@@ -680,6 +680,32 @@ When mocking time, `Date.now()` will also be mocked. If you for some reason need
 
 ## Misc
 
+### `jest.retryTimes(numRetries, options?)`
+
+Runs failed tests n-times until they pass or until the max number of retries is exhausted.
+
+```js
+jest.retryTimes(3);
+
+test('will fail', () => {
+  expect(true).toBe(false);
+});
+```
+
+Returns the `jest` object for chaining.
+
+:::caution
+
+`jest.retryTimes()` must be declared at the top level of a test file or in a `describe` block.
+
+:::
+
+:::info
+
+This function is only available with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner.
+
+:::
+
 ### `jest.setTimeout(timeout)`
 
 Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called.
@@ -695,18 +721,3 @@ Example:
 ```js
 jest.setTimeout(1000); // 1 second
 ```
-
-### `jest.retryTimes()`
-
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. This only works with [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus)!
-
-Example in a test:
-
-```js
-jest.retryTimes(3);
-test('will fail', () => {
-  expect(true).toBe(false);
-});
-```
-
-Returns the `jest` object for chaining.

website/versioned_docs/version-27.x/JestObjectAPI.md

@@ -720,6 +720,32 @@ When mocking time, `Date.now()` will also be mocked. If you for some reason need
 
 ## Misc
 
+### `jest.retryTimes(numRetries, options?)`
+
+Runs failed tests n-times until they pass or until the max number of retries is exhausted.
+
+```js
+jest.retryTimes(3);
+
+test('will fail', () => {
+  expect(true).toBe(false);
+});
+```
+
+Returns the `jest` object for chaining.
+
+:::caution
+
+`jest.retryTimes()` must be declared at the top level of a test file or in a `describe` block.
+
+:::
+
+:::info
+
+This function is only available with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner.
+
+:::
+
 ### `jest.setTimeout(timeout)`
 
 Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called.
@@ -735,18 +761,3 @@ Example:
 ```js
 jest.setTimeout(1000); // 1 second
 ```
-
-### `jest.retryTimes()`
-
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
-
-Example in a test:
-
-```js
-jest.retryTimes(3);
-test('will fail', () => {
-  expect(true).toBe(false);
-});
-```
-
-Returns the `jest` object for chaining.

website/versioned_docs/version-28.x/JestObjectAPI.md

@@ -837,42 +837,54 @@ This function is not available when using legacy fake timers implementation.
 
 ## Misc
 
-### `jest.setTimeout(timeout)`
-
-Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called.
-
-To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout).
-
-_Note: The default timeout interval is 5 seconds if this method is not called._
-
-_Note: If you want to set the timeout for all test files, a good place to do this is in `setupFilesAfterEnv`._
+### `jest.retryTimes(numRetries, options?)`
 
-Example:
-
-```js
-jest.setTimeout(1000); // 1 second
-```
-
-### `jest.retryTimes(numRetries, options)`
-
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. `options` are optional. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
-
-Example in a test:
+Runs failed tests n-times until they pass or until the max number of retries is exhausted.
 
 ```js
 jest.retryTimes(3);
+
 test('will fail', () => {
   expect(true).toBe(false);
 });
 ```
 
-If `logErrorsBeforeRetry` is enabled, Jest will log the error(s) that caused the test to fail to the console, providing visibility on why a retry occurred.
+If `logErrorsBeforeRetry` option is enabled, error(s) that caused the test to fail will be logged to the console.
 
 ```js
 jest.retryTimes(3, {logErrorsBeforeRetry: true});
+
 test('will fail', () => {
   expect(true).toBe(false);
 });
 ```
 
 Returns the `jest` object for chaining.
+
+:::caution
+
+`jest.retryTimes()` must be declared at the top level of a test file or in a `describe` block.
+
+:::
+
+:::info
+
+This function is only available with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner.
+
+:::
+
+### `jest.setTimeout(timeout)`
+
+Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called.
+
+To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout).
+
+_Note: The default timeout interval is 5 seconds if this method is not called._
+
+_Note: If you want to set the timeout for all test files, a good place to do this is in `setupFilesAfterEnv`._
+
+Example:
+
+```js
+jest.setTimeout(1000); // 1 second
+```

website/versioned_docs/version-29.0/JestObjectAPI.md

@@ -837,44 +837,56 @@ This function is not available when using legacy fake timers implementation.
 
 ## Misc
 
-### `jest.setTimeout(timeout)`
+### `jest.retryTimes(numRetries, options?)`
 
-Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called.
+Runs failed tests n-times until they pass or until the max number of retries is exhausted.
 
-Example:
+```js
+jest.retryTimes(3);
+
+test('will fail', () => {
+  expect(true).toBe(false);
+});
+```
+
+If `logErrorsBeforeRetry` option is enabled, error(s) that caused the test to fail will be logged to the console.
 
 ```js
-jest.setTimeout(1000); // 1 second
+jest.retryTimes(3, {logErrorsBeforeRetry: true});
+
+test('will fail', () => {
+  expect(true).toBe(false);
+});
 ```
 
-:::tip
+Returns the `jest` object for chaining.
 
-To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout).
+:::caution
 
-If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option.
+`jest.retryTimes()` must be declared at the top level of a test file or in a `describe` block.
 
 :::
 
-### `jest.retryTimes(numRetries, options)`
+:::info
 
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. `options` are optional. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
+This function is only available with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner.
 
-Example in a test:
+:::
 
-```js
-jest.retryTimes(3);
-test('will fail', () => {
-  expect(true).toBe(false);
-});
-```
+### `jest.setTimeout(timeout)`
+
+Set the default timeout interval (in milliseconds) for all tests and before/after hooks in the test file. This only affects the test file from which this function is called. The default timeout interval is 5 seconds if this method is not called.
 
-If `logErrorsBeforeRetry` is enabled, Jest will log the error(s) that caused the test to fail to the console, providing visibility on why a retry occurred.
+Example:
 
 ```js
-jest.retryTimes(3, {logErrorsBeforeRetry: true});
-test('will fail', () => {
-  expect(true).toBe(false);
-});
+jest.setTimeout(1000); // 1 second
 ```
 
-Returns the `jest` object for chaining.
+:::tip
+
+To set timeout intervals on different tests in the same file, use the [`timeout` option on each individual test](GlobalAPI.md#testname-fn-timeout).
+
+If you want to set the timeout for all test files, use [`testTimeout`](Configuration.md#testtimeout-number) configuration option.
+
+:::