Improve docs for Filters in ExUnit (:exclude and :include configuration) (#15118)

Author: eksperimental

lib/ex_unit/lib/ex_unit.ex

@@ -328,7 +328,8 @@ defmodule ExUnit do
         defaults to `IO.ANSI.color_background(0, 2, 0)`;
 
     * `:exclude` - specifies which tests are run by skipping tests that match the
-      filter. See the "Filters" section in the documentation for `ExUnit.Case`;
+      filter. For more information, see the "Tags" and "Filters" sections in the
+      documentation for `ExUnit.Case`;
 
     * `:exit_status` - specifies an alternate exit status to use when the test
       suite fails. Defaults to `2`;
@@ -342,8 +343,9 @@ defmodule ExUnit do
     * `:include` - specifies which tests are run by skipping tests that do not
       match the filter. Keep in mind that all tests are included by default, so unless they are
       excluded first, the `:include` option has no effect. To only run the tests
-      that match the `:include` filter, exclude the `:test` tag first (see the
-      documentation for `ExUnit.Case` for more information on tags and filters);
+      that match the `:include` filter, exclude the `:test` tag first.
+      For more information, see the "Tags" and "Filters" sections in the
+      documentation for `ExUnit.Case`;
 
     * `:max_cases` - maximum number of tests to run in parallel. Only tests from
       different modules run in parallel. It defaults to `System.schedulers_online * 2`

lib/ex_unit/lib/ex_unit/case.ex

@@ -196,6 +196,37 @@ defmodule ExUnit.Case do
 
     * `:tmp_dir` - (since v1.11.0) see the "Tmp Dir" section below
 
+  ## Filters
+
+  Tags can also be used to identify specific tests, which can then
+  be included or excluded using filters. The most common functionality
+  is to exclude some particular tests from running, which can be done
+  via `ExUnit.configure/1`:
+
+      # Exclude all external tests from running
+      ExUnit.configure(exclude: [external: true])
+
+  From now on, ExUnit will not run any test that has the `:external` option
+  set to `true`. This behaviour can be reversed with the `:include` option
+  which is usually passed through the command line:
+
+      $ mix test --include external:true
+
+  Run `mix help test` for more information on how to run filters via Mix.
+
+  Another use case for tags and filters is to exclude all tests that have
+  a particular tag by default, regardless of its value, and include only
+  a certain subset:
+
+      ExUnit.configure(exclude: :os, include: [os: :unix])
+
+  A given include/exclude filter can be given more than once:
+
+      ExUnit.configure(exclude: [os: :unix, os: :windows])
+
+  Keep in mind that all tests are included by default, so unless they are
+  excluded first, the `include` option has no effect.
+
   ## Parameterized tests
 
   Sometimes you want to run the same tests but with different parameters.
@@ -231,37 +262,6 @@ defmodule ExUnit.Case do
       may be the wrong solution to your problem. Consider creating separated
       tests and sharing logic between them using regular functions
 
-  ## Filters
-
-  Tags can also be used to identify specific tests, which can then
-  be included or excluded using filters. The most common functionality
-  is to exclude some particular tests from running, which can be done
-  via `ExUnit.configure/1`:
-
-      # Exclude all external tests from running
-      ExUnit.configure(exclude: [external: true])
-
-  From now on, ExUnit will not run any test that has the `:external` option
-  set to `true`. This behaviour can be reversed with the `:include` option
-  which is usually passed through the command line:
-
-      $ mix test --include external:true
-
-  Run `mix help test` for more information on how to run filters via Mix.
-
-  Another use case for tags and filters is to exclude all tests that have
-  a particular tag by default, regardless of its value, and include only
-  a certain subset:
-
-      ExUnit.configure(exclude: :os, include: [os: :unix])
-
-  A given include/exclude filter can be given more than once:
-
-      ExUnit.configure(exclude: [os: :unix, os: :windows])
-
-  Keep in mind that all tests are included by default, so unless they are
-  excluded first, the `include` option has no effect.
-
   ## Log Capture
 
   ExUnit can optionally suppress printing of log messages that are generated