A little more metacov

4 files changed, 30 insertions, 7 deletions

diff --git a/Makefile b/Makefile
index acd99f12..53d9dccc 100644
--- a/Makefile
+++ b/Makefile
@@ -67,6 +67,9 @@ pysmoke:
 	# Run tests with the Python tracer in the lowest supported Python versions.
 	COVERAGE_NO_CTRACER=1 tox -q -e py27,py35 -- $(PYTEST_SMOKE_ARGS)
 
+# Coverage measurement of coverage.py itself (meta-coverage). See metacov.ini
+# for details.
+
 metacov:
 	COVERAGE_COVERAGE=yes tox $(ARGS)
 
diff --git a/coverage/debug.py b/coverage/debug.py
index c5fee683..c713978a 100644
--- a/coverage/debug.py
+++ b/coverage/debug.py
@@ -201,7 +201,7 @@ class SimpleReprMixin(object):
             )
 
 
-def simplify(v):
+def simplify(v):                                            # pragma: debugging
     """Turn things which are nearly dict/list/etc into dict/list/etc."""
     if isinstance(v, dict):
         return {k:simplify(vv) for k, vv in v.items()}
@@ -213,7 +213,7 @@ def simplify(v):
         return v
 
 
-def pp(v):
+def pp(v):                                                  # pragma: debugging
     """Debug helper to pretty-print data, including SimpleNamespace objects."""
     pprint.pprint(simplify(v))
 
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.
diff --git a/tests/test_api.py b/tests/test_api.py
index b1532cf1..786d6aab 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -514,7 +514,7 @@ class ApiTest(CoverageTest):
         cov = coverage.Coverage()
         cov.start()
 
-        if "# pragma: nested":
+        if "pragma: nested":
             # Imports the test suite
             suite = import_local_file("testsuite")
 
@@ -555,7 +555,7 @@ class ApiTest(CoverageTest):
         cov = coverage.Coverage(context="mysuite")
         cov.start()
 
-        if "# pragma: nested":
+        if "pragma: nested":
             # Imports the test suite
             suite = import_local_file("testsuite")