Improve doc for data kwarg.

anntzer · anntzer · commit 67ef9117fe0c · 2019-12-10T22:36:19.000+01:00
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1402,14 +1402,12 @@ def _label_from_arg(y, default_name):
 _DATA_DOC_APPENDIX = """
 
 .. note::
-    In addition to the above described arguments, this function can take a
-    **data** keyword argument. If such a **data** argument is given, the
-    following arguments are replaced by **data[<arg>]**:
+    In addition to the above described arguments, this function can take
+    a *data* keyword argument. If such a *data* argument is given,
+{replaced}
 
-    {replaced}
-
-    Objects passed as **data** must support item access (``data[<arg>]``) and
-    membership test (``<arg> in data``).
+    Objects passed as **data** must support item access (``data[s]``) and
+    membership test (``s in data``).
 """
 
 
@@ -1429,13 +1427,17 @@ def _add_data_doc(docstring, replace_names):
     -------
         The augmented docstring.
     """
-    docstring = inspect.cleandoc(docstring) if docstring is not None else ""
-    repl = ("* All positional and all keyword arguments."
-            if replace_names is None else
-            ""
-            if len(replace_names) == 0 else
-            "* All arguments with the following names: {}.".format(
-                ", ".join(map(repr, sorted(replace_names)))))
+    if (docstring is None
+            or replace_names is not None and len(replace_names) == 0):
+        return docstring
+    docstring = inspect.cleandoc(docstring)
+    repl = (
+        ("    every other argument can also be string ``s``, which is\n"
+         "    interpreted as ``data[s]`` (unless this raises an exception).")
+        if replace_names is None else
+        ("    the following arguments can also be string ``s``, which is\n"
+         "    interpreted as ``data[s]`` (unless this raises an exception):\n"
+         "    " + ", ".join(map("*{}*".format, replace_names))) + ".")
     addendum = _DATA_DOC_APPENDIX.format(replaced=repl)
     if _DATA_DOC_TITLE not in docstring:
         addendum = _DATA_DOC_TITLE + addendum
diff --git a/lib/matplotlib/tests/test_preprocess_data.py b/lib/matplotlib/tests/test_preprocess_data.py
@@ -189,50 +189,29 @@ def test_docstring_addition():
     @_preprocess_data()
     def funcy(ax, *args, **kwargs):
         """Funcy does nothing"""
-        pass
 
-    assert re.search(r".*All positional and all keyword arguments\.",
-                     funcy.__doc__)
-    assert not re.search(r".*All positional arguments\.",
-                         funcy.__doc__)
-    assert not re.search(r".*All arguments with the following names: .*",
-                         funcy.__doc__)
+    assert re.search(r"every other argument", funcy.__doc__)
+    assert not re.search(r"the following arguments", funcy.__doc__)
 
     @_preprocess_data(replace_names=[])
     def funcy(ax, x, y, z, bar=None):
         """Funcy does nothing"""
-        pass
 
-    assert not re.search(r".*All positional arguments\.",
-                         funcy.__doc__)
-    assert not re.search(r".*All positional and all keyword arguments\.",
-                         funcy.__doc__)
-    assert not re.search(r".*All arguments with the following names: .*",
-                         funcy.__doc__)
+    assert not re.search(r"every other argument", funcy.__doc__)
+    assert not re.search(r"the following arguments", funcy.__doc__)
 
     @_preprocess_data(replace_names=["bar"])
     def funcy(ax, x, y, z, bar=None):
         """Funcy does nothing"""
-        pass
 
-    assert not re.search(r".*All positional arguments\.",
-                         funcy.__doc__)
-    assert re.search(r".*All arguments with the following names: 'bar'\.",
-                     funcy.__doc__)
-    assert not re.search(r".*All positional and all keyword arguments\.",
+    assert not re.search(r"every other argument", funcy.__doc__)
+    assert not re.search(r"the following arguments .*: \*bar\*\.",
                          funcy.__doc__)
 
-    @_preprocess_data(replace_names=["x", "bar"])
-    def funcy(ax, x, y, z, bar=None):
+    @_preprocess_data(replace_names=["x", "t"])
+    def funcy(ax, x, y, z, t=None):
         """Funcy does nothing"""
-        pass
 
-    # lists can print in any order, so test for both x, bar and bar, x.
-    assert re.search(r".*All arguments with the following names: '.*', '.*'\.",
-                     funcy.__doc__)
-    assert re.search(r".*'x'.*", funcy.__doc__)
-    assert re.search(r".*'bar'.*", funcy.__doc__)
-    assert not re.search(r".*All positional and all keyword arguments\.",
-                         funcy.__doc__)
-    assert not re.search(r".*All positional arguments\.",
+    assert not re.search(r"every other argument", funcy.__doc__)
+    assert not re.search(r"the following arguments .*: \*x\*, \*t\*\.",
                          funcy.__doc__)
