Clarify when coverage measurement actually starts. #102

2 files changed, 11 insertions, 3 deletions

diff --git a/coverage/control.py b/coverage/control.py
index 20afff5..6f15bf9 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -25,7 +25,7 @@ class coverage(object):
 
         cov = coverage()
         cov.start()
-        #.. blah blah (run your code) blah blah ..
+        #.. call your code ..
         cov.stop()
         cov.html_report(directory='covhtml')
 
@@ -320,7 +320,12 @@ class coverage(object):
         self.data.read()
 
     def start(self):
-        """Start measuring code coverage."""
+        """Start measuring code coverage.
+
+        Coverage measurement actually occurs in functions called after `start`
+        is invoked.  Statements in the same scope as `start` won't be measured.
+
+        """
         if self.run_suffix:
             # Calling start() means we're running code, so use the run_suffix
             # as the data_suffix when we eventually save the data.
diff --git a/doc/api.rst b/doc/api.rst
index 09b94af..9ce1ee1 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -8,6 +8,7 @@ Coverage API
 :history: 20090613T164000, final touches for 3.0
 :history: 20100221T151500, docs for 3.3 (on the plane back from PyCon)
 :history: 20100725T211700, updated for 3.4.
+:history: 20121111T235800, added a bit of clarification.
 
 
 The API to coverage.py is very simple, contained in a single module called
@@ -20,11 +21,13 @@ in the command line interface. For example, a simple use would be::
     cov = coverage.coverage()
     cov.start()
 
-    # .. run your code ..
+    # .. call your code ..
 
     cov.stop()
     cov.save()
 
+    cov.html_report()
+
 
 The coverage module
 -------------------