More docs about dynamic contexts

1 files changed, 25 insertions, 13 deletions

diff --git a/coverage/plugin.py b/coverage/plugin.py
index e817cf2f..5f66dfb9 100644
--- a/coverage/plugin.py
+++ b/coverage/plugin.py
@@ -14,6 +14,9 @@ behavior:
 * Configurers add custom configuration, using Python code to change the
   configuration.
 
+* Dynamic context switchers decide when the dynamic context has changed, for
+  example, to record what test function produced the coverage.
+
 To write a coverage.py plug-in, create a module with a subclass of
 :class:`~coverage.CoveragePlugin`.  You will override methods in your class to
 participate in various aspects of coverage.py's processing.
@@ -78,25 +81,29 @@ change the configuration.
 In your ``coverage_init`` function, use the ``add_configurer`` method to
 register your configurer.
 
-Dynamic Contexts
-================
+.. _dynamic_context_plugins:
+
+Dynamic Context Switchers
+=========================
 
 .. versionadded:: 5.0
 
-Context plugins implement the :meth:`~coverage.CoveragePlugin.dynamic_context` method
-to dynamically compute the context label for each measured frame.
+Dynamic context switcher plugins implement the
+:meth:`~coverage.CoveragePlugin.dynamic_context` method to dynamically compute
+the context label for each measured frame.
 
 Computed context labels are useful when you want to group measured data without
 modifying the source code.
 
-For example, you could write a plugin that check `frame.f_code` to inspect
-the currently executed method, and set label to a fully qualified method
-name if it's an instance method of `unittest.TestCase` and the method name
-starts with 'test'.  Such plugin would provide basic coverage grouping by test
-and could be used with test runners that have no built-in coveragepy support.
+For example, you could write a plugin that checks `frame.f_code` to inspect
+the currently executed method, and set the context label to a fully qualified
+method name if it's an instance method of `unittest.TestCase` and the method
+name starts with 'test'.  Such a plugin would provide basic coverage grouping
+by test and could be used with test runners that have no built-in coveragepy
+support.
 
 In your ``coverage_init`` function, use the ``add_dynamic_context`` method to
-register your file tracer.
+register your dynamic context switcher.
 
 """
 
@@ -161,12 +168,17 @@ class CoveragePlugin(object):
         _needs_to_implement(self, "file_reporter")
 
     def dynamic_context(self, frame):       # pylint: disable=unused-argument
-        """Get dynamically computed context label for collected data.
+        """Get the dynamically computed context label for `frame`.
 
         Plug-in type: dynamic context.
 
-        This method is invoked for each frame.  If it returns a string,
-        a new context label is set for this and deeper frames.
+        This method is invoked for each frame when outside of a dynamic
+        context, to see if a new dynamic context should be started.  If it
+        returns a string, a new context label is set for this and deeper
+        frames.  The dynamic context ends when this frame returns.
+
+        Returns a string to start a new dynamic context, or None if no new
+        context should be started.
 
         """
         return None