Update documentation for --filter CLI option (see #12260)

CHANGELOG.md

@@ -11,6 +11,7 @@
 
 ### Chore & Maintenance
 
+- `[docs]` Specified documentation about `--filter` CLI docs ([#12799](https://github.com/facebook/jest/pull/12799))
 - `[@jest-reporters]` Move helper functions from `utils.ts` into separate files ([#12782](https://github.com/facebook/jest/pull/12782))
 - `[jest-resolve]` Replace `process.versions.pnp` type declaration with `@types/pnpapi` devDependency ([#12783](https://github.com/facebook/jest/pull/12783))
 

docs/CLI.md

@@ -204,7 +204,16 @@ Alias: `-e`. Use this flag to show full diffs and errors instead of a patch.
 
 ### `--filter=<file>`
 
-Path to a module exporting a filtering function. This method receives a list of tests which can be manipulated to exclude tests from running. Especially useful when used in conjunction with a testing infrastructure to filter known broken.
+Path to a module exporting a filtering function. This asynchronous function receives a list of test paths which can be manipulated to exclude tests from running by returning an object with the "filtered" property. Especially useful when used in conjunction with a testing infrastructure to filter known broken, e.g.
+
+```js title="my-filter.js"
+module.exports = testPaths => {
+  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]
+  return {
+    filtered: allowedPaths,
+  };
+};
+```
 
 ### `--findRelatedTests <spaceSeparatedListOfSourceFiles>`
 

website/versioned_docs/version-28.0/CLI.md

@@ -204,7 +204,16 @@ Alias: `-e`. Use this flag to show full diffs and errors instead of a patch.
 
 ### `--filter=<file>`
 
-Path to a module exporting a filtering function. This method receives a list of tests which can be manipulated to exclude tests from running. Especially useful when used in conjunction with a testing infrastructure to filter known broken.
+Path to a module exporting a filtering function. This asynchronous function receives a list of test paths which can be manipulated to exclude tests from running by returning an object with the "filtered" property. Especially useful when used in conjunction with a testing infrastructure to filter known broken, e.g.
+
+```js title="my-filter.js"
+module.exports = testPaths => {
+  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]
+  return {
+    filtered: allowedPaths,
+  };
+};
+```
 
 ### `--findRelatedTests <spaceSeparatedListOfSourceFiles>`