A little more metacov

1 files changed, 23 insertions, 3 deletions

diff --git a/metacov.ini b/metacov.ini
index 60b4ea3c..c9404612 100644
--- a/metacov.ini
+++ b/metacov.ini
@@ -1,7 +1,11 @@
 # Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
 # For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
 
-# Settings to use when using coverage.py to measure itself.
+# Settings to use when using coverage.py to measure itself, known as
+# meta-coverage.  This gets intricate because we need to keep the coverage
+# measurement happening in the tests separate from our own coverage measurement
+# of coverage.py itself.
+
 [run]
 branch = true
 data_file = ${COVERAGE_METAFILE?}
@@ -13,11 +17,27 @@ source =
 dynamic_context = ${COVERAGE_CONTEXT-none}
 
 [report]
-# We set a different pragma so our code won't be confused with test code.
+# We set a different pragmas so our code won't be confused with test code, and
+# we use different pragmas for different reasons that the lines won't be
+# measured.
 exclude_lines =
     pragma: not covered
 
-    # Lines in test code that isn't covered: we are nested inside ourselves.
+    # Lines in test code that aren't covered: we are nested inside ourselves.
+    # Sometimes this is used as a comment:
+    #
+    #       cov.start()
+    #       blah()              # pragma: nested
+    #       cov.stop()          # pragma: nested
+    #
+    # In order to exclude a series of lines, sometimes it's used as a constant
+    # condition, which might be too cute:
+    #
+    #       cov.start()
+    #       if "pragma: nested":
+    #           blah()
+    #           cov.stop()
+    #
     pragma: nested
 
     # Lines that are only executed when we are debugging coverage.py.