docs: lean harder on [report] exclude_also.

3 files changed, 27 insertions, 25 deletions

diff --git a/doc/config.rst b/doc/config.rst
index f81d7d00..0100d89e 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -79,10 +79,7 @@ Here's a sample configuration file::
 
     [report]
     # Regexes for lines to exclude from consideration
-    exclude_lines =
-        # Have to re-enable the standard pragma
-        pragma: no cover
-
+    exclude_also =
         # Don't complain about missing debug-only code:
         def __repr__
         if self\.debug
@@ -375,6 +372,19 @@ See :ref:`cmd_combine_remapping` and :ref:`source_glob` for more information.
 Settings common to many kinds of reporting.
 
 
+.. _config_report_exclude_also:
+
+[report] exclude_also
+.....................
+
+(multi-string) A list of regular expressions.  This setting is similar to
+:ref:`config_report_exclude_lines`: it specifies patterns for lines to exclude
+from reporting.  This setting is preferred, because it will preserve the
+default exclude patterns instead of overwriting them.
+
+.. versionadded:: 7.2.0
+
+
 .. _config_report_exclude_lines:
 
 [report] exclude_lines
@@ -397,19 +407,6 @@ you'll exclude any line with three or more of any character. If you write
 ``pass``, you'll also exclude the line ``my_pass="foo"``, and so on.
 
 
-.. _config_report_exclude_also:
-
-[report] exclude_also
-.....................
-
-(multi-string) A list of regular expressions.  This setting is similar to
-:ref:`config_report_exclude_lines`: it specifies patterns for lines to exclude
-from reporting.  The difference is this setting will preserve the default
-exclude patterns instead of overwriting them.
-
-.. versionadded:: 7.2.0
-
-
 .. _config_report_fail_under:
 
 [report] fail_under
diff --git a/doc/excluding.rst b/doc/excluding.rst
index 4651e6bb..e9d28f15 100644
--- a/doc/excluding.rst
+++ b/doc/excluding.rst
@@ -80,14 +80,13 @@ debugging code, and are uninteresting to test themselves.  You could exclude
 all of them by adding a regex to the exclusion list::
 
     [report]
-    exclude_lines =
+    exclude_also =
         def __repr__
 
 For example, here's a list of exclusions I've used::
 
     [report]
-    exclude_lines =
-        pragma: no cover
+    exclude_also =
         def __repr__
         if self.debug:
         if settings.DEBUG
@@ -99,11 +98,10 @@ For example, here's a list of exclusions I've used::
         class .*\bProtocol\):
         @(abc\.)?abstractmethod
 
-Note that when using the ``exclude_lines`` option in a configuration file, you
-are taking control of the entire list of regexes, so you need to re-specify the
-default "pragma: no cover" match if you still want it to apply.  The
-``exclude_also`` option can be used instead to preserve the default
-exclusions while adding new ones.
+The :ref:`config_report_exclude_also` option adds regexes to the built-in
+default list so that you can add your own exclusions.  The older
+:ref:`config_report_exclude_lines` option completely overwrites the list of
+regexes.
 
 The regexes only have to match part of a line. Be careful not to over-match.  A
 value of ``...`` will match any line with more than three characters in it.
diff --git a/doc/migrating.rst b/doc/migrating.rst
index 7a5e65df..996c19cb 100644
--- a/doc/migrating.rst
+++ b/doc/migrating.rst
@@ -27,3 +27,10 @@ Migrating from 6.x to 7.x
 - When remapping file paths with ``[paths]``, a path will be remapped only if
   the resulting path exists. Ensure that remapped ``[paths]`` exist when upgrading
   as this is now being enforced.
+
+- The :ref:`config_report_exclude_also` setting is new in 7.2.0.  It adds
+  exclusion regexes while keeping the default built-in set. It's better than
+  the older :ref:`config_report_exclude_lines` setting, which overwrote the
+  entire list.  Newer versions of coverage.py will be adding to the default set
+  of exclusions.  Using ``exclude_also`` will let you benefit from those
+  updates.