Finish up #967. Thanks, Bernát Gábor

2 files changed, 10 insertions, 1 deletions

diff --git a/coverage/config.py b/coverage/config.py
index 166f34ea..7876052b 100644
--- a/coverage/config.py
+++ b/coverage/config.py
@@ -421,6 +421,7 @@ class CoverageConfig(object):
         `value` is the new value for the option.
 
         """
+        # Special-cased options.
         if option_name == "paths":
             self.paths = value
             return
@@ -451,6 +452,7 @@ class CoverageConfig(object):
         Returns the value of the option.
 
         """
+        # Special-cased options.
         if option_name == "paths":
             return self.paths
 
diff --git a/coverage/control.py b/coverage/control.py
index f7db26e9..2b8c3d26 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -367,7 +367,11 @@ class Coverage(object):
         option name.  For example, the ``branch`` option in the ``[run]``
         section of the config file would be indicated with `"run:branch"`.
 
-        Returns the value of the option.
+        Returns the value of the option.  The type depends on the option
+        selected.
+
+        As a special case, an `option_name` of ``"paths"`` will return an
+        OrderedDict with the entire ``[paths]`` section value.
 
         .. versionadded:: 4.0
 
@@ -394,6 +398,9 @@ class Coverage(object):
             [run]
             branch = True
 
+        As a special case, an `option_name` of ``"paths"`` will replace the
+        entire ``[paths]`` section.  The value should be an OrderedDict.
+
         .. versionadded:: 4.0
 
         """