docs: clarify the behavior of exclude_lines

2 files changed, 23 insertions, 2 deletions

diff --git a/doc/config.rst b/doc/config.rst
index 34da8a06..db85ba33 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -89,6 +89,9 @@ Here's a sample configuration file::
         if 0:
         if __name__ == .__main__.:
 
+        # Don't complain about abstract methods, they aren't run:
+        @(abc\.)?abstractmethod
+
     ignore_errors = True
 
     [html]
@@ -267,11 +270,20 @@ Values common to many kinds of reporting.
 .. _config_report_exclude_lines:
 
 ``exclude_lines`` (multi-string): a list of regular expressions.  Any line of
-your source code that matches one of these regexes is excluded from being
+your source code containing a match for  one of these regexes is excluded from
+being
 reported as missing.  More details are in :ref:`excluding`.  If you use this
 option, you are replacing all the exclude regexes, so you'll need to also
 supply the "pragma: no cover" regex if you still want to use it.
 
+You can exclude lines introducing blocks, and the entire block is excluded. If
+you exclude a ``def`` line or decorator line, the entire function is excluded.
+
+Be careful when writing this setting: the values are regular expressions that
+only have to match a portion of the line. For example, if you write ``...``,
+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_fail_under:
 
 ``fail_under`` (float): a target coverage percentage. If the total coverage
diff --git a/doc/excluding.rst b/doc/excluding.rst
index 0db7c16d..b89d449c 100644
--- a/doc/excluding.rst
+++ b/doc/excluding.rst
@@ -67,12 +67,17 @@ expressions. Using :ref:`configuration files <config>` or the coverage
 often-used constructs to exclude that can be matched with a regex. You can
 exclude them all at once without littering your code with exclusion pragmas.
 
+If the matched line introduces a block, the entire block is excluded from
+reporting.  Matching a ``def`` line or decorator line will exclude an entire
+function.
+
 For example, you might decide that __repr__ functions are usually only used in
 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 = def __repr__
+    exclude_lines =
+        def __repr__
 
 For example, here's a list of exclusions I've used::
 
@@ -87,11 +92,15 @@ For example, here's a list of exclusions I've used::
         if 0:
         if __name__ == .__main__.:
         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 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.
+
 A similar pragma, "no branch", can be used to tailor branch coverage
 measurement.  See :ref:`branch` for details.