Deduplicate inherited docstrings.

anntzer · anntzer · commit c83d6acc3165 · 2018-09-25T13:34:41.000+02:00
Since Py3.5, inspect.getdoc inherits method docstrings from
super-methods (pydoc, sphinx, and IPython's ? do the same).

Take advantage of this to deduplicate some docstrings that were already
defined for the Artist base methods.  Note that Text.set_clip_path's
docstring had actually not been updated when we updated the docstring of
Artist.set_clip_path...

We could add a decorator to check that the docstring is *actually*
getting inherited but that seems totally overkill.
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1191,7 +1191,7 @@ def get_aliases(self):
             if not self.is_alias(func):
                 continue
             propname = re.search("`({}.*)`".format(name[:4]),  # get_.*/set_.*
-                                 func.__doc__).group(1)
+                                 inspect.getdoc(func)).group(1)
             aliases.setdefault(propname, set()).add(name[4:])
         return aliases
 
@@ -1213,7 +1213,7 @@ def get_valid_values(self, attr):
             raise AttributeError('%s has no function %s' % (self.o, name))
         func = getattr(self.o, name)
 
-        docstring = func.__doc__
+        docstring = inspect.getdoc(func)
         if docstring is None:
             return 'unknown'
 
@@ -1229,7 +1229,7 @@ def get_valid_values(self, attr):
         param_name = func.__code__.co_varnames[1]
         # We could set the presence * based on whether the parameter is a
         # varargs (it can't be a varkwargs) but it's not really worth the it.
-        match = re.search("(?m)^ *\*?{} : (.+)".format(param_name), docstring)
+        match = re.search(r"(?m)^ *\*?{} : (.+)".format(param_name), docstring)
         if match:
             return match.group(1)
 
@@ -1279,7 +1279,7 @@ def get_setters(self):
 
     def is_alias(self, o):
         """Return whether method object *o* is an alias for another method."""
-        ds = o.__doc__
+        ds = inspect.getdoc(o)
         if ds is None:
             return False
         return ds.startswith('Alias for ')
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1659,7 +1659,7 @@ def set_pickradius(self, pickradius):
         self.pickradius = pickradius
 
     def set_ticklabels(self, ticklabels, *args, minor=False, **kwargs):
-        """
+        r"""
         Set the text values of the tick labels.
 
         Parameters
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -258,9 +258,9 @@ def test_None_zorder():
 
 @pytest.mark.parametrize('accept_clause, expected', [
     ('', 'unknown'),
-    ("ACCEPTS: [ '-' | '--' | '-.' ]", "[ '-' | '--' | '-.' ] "),
-    ('ACCEPTS: Some description.', 'Some description. '),
-    ('.. ACCEPTS: Some description.', 'Some description. '),
+    ("ACCEPTS: [ '-' | '--' | '-.' ]", "[ '-' | '--' | '-.' ]"),
+    ('ACCEPTS: Some description.', 'Some description.'),
+    ('.. ACCEPTS: Some description.', 'Some description.'),
     ('arg : int', 'int'),
     ('*arg : int', 'int'),
     ('arg : int\nACCEPTS: Something else.', 'Something else. '),
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
@@ -542,50 +542,17 @@ def _update_clip_properties(self):
             bbox = self._bbox_patch.update(clipprops)
 
     def set_clip_box(self, clipbox):
-        """
-        Set the artist's clip `~.transforms.Bbox`.
-
-        Parameters
-        ----------
-        clipbox : `matplotlib.transforms.Bbox`
-        """
+        # docstring inherited.
         super().set_clip_box(clipbox)
         self._update_clip_properties()
 
     def set_clip_path(self, path, transform=None):
-        """
-        Set the artist's clip path, which may be:
-
-          * a `~matplotlib.patches.Patch` (or subclass) instance
-
-          * a `~matplotlib.path.Path` instance, in which case
-             an optional `~matplotlib.transforms.Transform`
-             instance may be provided, which will be applied to the
-             path before using it for clipping.
-
-          * *None*, to remove the clipping path
-
-        For efficiency, if the path happens to be an axis-aligned
-        rectangle, this method will set the clipping box to the
-        corresponding rectangle and set the clipping path to *None*.
-
-        ACCEPTS: { (`.path.Path`, `.transforms.Transform`),
-                  `.patches.Patch`, None }
-        """
+        # docstring inherited.
         super().set_clip_path(path, transform)
         self._update_clip_properties()
 
     def set_clip_on(self, b):
-        """
-        Set whether artist uses clipping.
-
-        When False, artists will be visible outside of the axes, which can lead
-        to unexpected results.
-
-        Parameters
-        ----------
-        b : bool
-        """
+        # docstring inherited.
         super().set_clip_on(b)
         self._update_clip_properties()
 
@@ -1261,7 +1228,7 @@ def get_usetex(self):
 
     def set_fontname(self, fontname):
         """
-        Alias for `.set_family`.
+        Alias for `set_family`.
 
         One-way alias only: the getter differs.
 
