Merge pull request #14341 from meeseeksmachine/auto-backport-of-pr-14337-on-v3.1.x

dstansby · web-flow · commit 31ab80298a09 · 2019-05-27T11:49:12.000+01:00
Backport PR #14337 on branch v3.1.x (Docstring cleanup)
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1064,12 +1064,12 @@ def get_ticklabel_extents(self, renderer):
         return bbox, bbox2
 
     def set_smart_bounds(self, value):
-        """set the axis to have smart bounds"""
+        """Set the axis to have smart bounds."""
         self._smart_bounds = value
         self.stale = True
 
     def get_smart_bounds(self):
-        """get whether the axis has smart bounds"""
+        """Return whether the axis has smart bounds."""
         return self._smart_bounds
 
     def _update_ticks(self):
diff --git a/lib/matplotlib/backends/_backend_tk.py b/lib/matplotlib/backends/_backend_tk.py
@@ -339,7 +339,7 @@ def idle_draw(*args):
         self._idle_callback = self._tkcanvas.after_idle(idle_draw)
 
     def get_tk_widget(self):
-        """returns the Tk widget used to implement FigureCanvasTkAgg.
+        """Return the Tk widget used to implement FigureCanvasTkAgg.
         Although the initial implementation uses a Tk canvas,  this routine
         is intended to hide that fact.
         """
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -63,7 +63,7 @@ def get_subplot_params(self, figure=None, fig=None):
 
     def new_subplotspec(self, loc, rowspan=1, colspan=1):
         """
-        create and return a SubplotSpec instance.
+        Create and return a SubplotSpec instance.
         """
         loc1, loc2 = loc
         subplotspec = self[loc1:loc1+rowspan, loc2:loc2+colspan]
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -128,7 +128,7 @@ def validate_bool(b):
 
 
 def validate_bool_maybe_none(b):
-    'Convert b to a boolean or raise'
+    """Convert b to a boolean or raise."""
     if isinstance(b, str):
         b = b.lower()
     if b is None or b == 'none':
@@ -142,7 +142,7 @@ def validate_bool_maybe_none(b):
 
 
 def validate_float(s):
-    """convert s to float or raise"""
+    """Convert s to float or raise."""
     try:
         return float(s)
     except ValueError:
@@ -151,7 +151,7 @@ def validate_float(s):
 
 
 def validate_float_or_None(s):
-    """convert s to float, None or raise"""
+    """Convert s to float, None or raise."""
     # values directly from the rc file can only be strings,
     # so we need to recognize the string "None" and convert
     # it into the object. We will be case-sensitive here to
@@ -166,7 +166,7 @@ def validate_float_or_None(s):
 
 
 def validate_string_or_None(s):
-    """convert s to string or raise"""
+    """Convert s to string or raise."""
     if s is None:
         return None
     try:
@@ -202,7 +202,7 @@ def validate_axisbelow(s):
 
 
 def validate_dpi(s):
-    """confirm s is string 'figure' or convert s to float or raise"""
+    """Confirm s is string 'figure' or convert s to float or raise."""
     if s == 'figure':
         return s
     try:
@@ -213,15 +213,15 @@ def validate_dpi(s):
 
 
 def validate_int(s):
-    """convert s to int or raise"""
+    """Convert s to int or raise."""
     try:
         return int(s)
     except ValueError:
         raise ValueError('Could not convert "%s" to int' % s)
 
 
 def validate_int_or_None(s):
-    """if not None, tries to validate as an int"""
+    """Return None if s is None or return ``int(s)``, otherwise raise."""
     if s == 'None':
         s = None
     if s is None:
@@ -234,8 +234,8 @@ def validate_int_or_None(s):
 
 def validate_fonttype(s):
     """
-    confirm that this is a Postscript of PDF font type that we know how to
-    convert to
+    Confirm that this is a Postscript or PDF font type that we know how to
+    convert to.
     """
     fonttypes = {'type3':    3,
                  'truetype': 42}
@@ -302,7 +302,7 @@ def __init__(self, n=None, allow_none=False):
         self.allow_none = allow_none
 
     def __call__(self, s):
-        """return a seq of n floats or raise"""
+        """Return a list of *n* floats or raise."""
         if isinstance(s, str):
             s = [x.strip() for x in s.split(',')]
             err_msg = _str_err_msg
@@ -326,7 +326,7 @@ def __init__(self, n=None):
         self.n = n
 
     def __call__(self, s):
-        """return a seq of n ints or raise"""
+        """Return a list of *n* ints or raise."""
         if isinstance(s, str):
             s = [x.strip() for x in s.split(',')]
             err_msg = _str_err_msg
@@ -343,7 +343,7 @@ def __call__(self, s):
 
 
 def validate_color_or_inherit(s):
-    'return a valid color arg'
+    """Return a valid color arg."""
     if s == 'inherit':
         return s
     return validate_color(s)
@@ -372,7 +372,7 @@ def validate_color_for_prop_cycle(s):
 
 
 def validate_color(s):
-    'return a valid color arg'
+    """Return a valid color arg."""
     try:
         if s.lower() == 'none':
             return 'none'
@@ -864,7 +864,7 @@ def cycler(*args, **kwargs):
 
 
 def validate_cycler(s):
-    'return a Cycler object from a string repr or the object itself'
+    """Return a Cycler object from a string repr or the object itself."""
     if isinstance(s, str):
         try:
             # TODO: We might want to rethink this...
diff --git a/lib/matplotlib/spines.py b/lib/matplotlib/spines.py
@@ -79,7 +79,7 @@ def __init__(self, axes, spine_type, path, **kwargs):
         self._patch_transform = mtransforms.IdentityTransform()
 
     def set_smart_bounds(self, value):
-        """set the spine and associated axis to have smart bounds"""
+        """Set the spine and associated axis to have smart bounds."""
         self._smart_bounds = value
 
         # also set the axis if possible
@@ -90,11 +90,11 @@ def set_smart_bounds(self, value):
         self.stale = True
 
     def get_smart_bounds(self):
-        """get whether the spine has smart bounds"""
+        """Return whether the spine has smart bounds."""
         return self._smart_bounds
 
     def set_patch_arc(self, center, radius, theta1, theta2):
-        """set the spine to be arc-like"""
+        """Set the spine to be arc-like."""
         self._patch_type = 'arc'
         self._center = center
         self._width = radius * 2
@@ -107,7 +107,7 @@ def set_patch_arc(self, center, radius, theta1, theta2):
         self.stale = True
 
     def set_patch_circle(self, center, radius):
-        """set the spine to be circular"""
+        """Set the spine to be circular."""
         self._patch_type = 'circle'
         self._center = center
         self._width = radius * 2
@@ -117,7 +117,7 @@ def set_patch_circle(self, center, radius):
         self.stale = True
 
     def set_patch_line(self):
-        """set the spine to be linear"""
+        """Set the spine to be linear."""
         self._patch_type = 'line'
         self.stale = True
 
@@ -212,7 +212,7 @@ def _ensure_position_is_set(self):
             self.set_position(self._position)
 
     def register_axis(self, axis):
-        """register an axis
+        """Register an axis.
 
         An axis should be registered with its corresponding spine from
         the Axes instance. This allows the spine to clear any axis
@@ -224,14 +224,14 @@ def register_axis(self, axis):
         self.stale = True
 
     def cla(self):
-        """Clear the current spine"""
+        """Clear the current spine."""
         self._position = None  # clear position
         if self.axis is not None:
             self.axis.cla()
 
     @cbook.deprecated("3.1")
     def is_frame_like(self):
-        """return True if directly on axes frame
+        """Return True if directly on axes frame.
 
         This is useful for determining if a spine is the edge of an
         old style MPL plot. If so, this function will return True.
@@ -252,7 +252,7 @@ def is_frame_like(self):
             return False
 
     def _adjust_location(self):
-        """automatically set spine bounds to the view interval"""
+        """Automatically set spine bounds to the view interval."""
 
         if self.spine_type == 'circle':
             return
@@ -367,7 +367,7 @@ def draw(self, renderer):
         return ret
 
     def _calc_offset_transform(self):
-        """calculate the offset transform performed by the spine"""
+        """Calculate the offset transform performed by the spine."""
         self._ensure_position_is_set()
         position = self._position
         if isinstance(position, str):
@@ -441,7 +441,7 @@ def _calc_offset_transform(self):
                                          mtransforms.IdentityTransform())
 
     def set_position(self, position):
-        """set the position of the spine
+        """Set the position of the spine.
 
         Spine position is specified by a 2 tuple of (position type,
         amount). The position types are:
@@ -480,12 +480,12 @@ def set_position(self, position):
         self.stale = True
 
     def get_position(self):
-        """get the spine position"""
+        """Return the spine position."""
         self._ensure_position_is_set()
         return self._position
 
     def get_spine_transform(self):
-        """get the spine transform"""
+        """Return the spine transform."""
         self._ensure_position_is_set()
         what, how = self._spine_transform
 
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -638,7 +638,7 @@ def set_active(self, index):
 
     def get_status(self):
         """
-        returns a tuple of the status (True/False) of all of the check buttons
+        Return a tuple of the status (True/False) of all of the check buttons.
         """
         return [l1.get_visible() for (l1, l2) in self.lines]
 
diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py
@@ -604,7 +604,7 @@ def new_vertical(self, size, pad=None, pack_start=False, **kwargs):
     def append_axes(self, position, size, pad=None, add_to_figure=True,
                     **kwargs):
         """
-        create an axes at the given *position* with the same height
+        Create an axes at the given *position* with the same height
         (or width) of the main axes.
 
          *position*
@@ -703,9 +703,8 @@ def _calc_offsets(appended_sizes, karray):
 
     def new_locator(self, nx, nx1=None):
         """
-        returns a new locator
-        (:class:`mpl_toolkits.axes_grid.axes_divider.AxesLocator`) for
-        specified cell.
+        Create a new `~mpl_toolkits.axes_grid.axes_divider.AxesLocator` for
+        the specified cell.
 
         Parameters
         ----------
@@ -796,9 +795,8 @@ class VBoxDivider(HBoxDivider):
 
     def new_locator(self, ny, ny1=None):
         """
-        returns a new locator
-        (:class:`mpl_toolkits.axes_grid.axes_divider.AxesLocator`) for
-        specified cell.
+        Create a new `~mpl_toolkits.axes_grid.axes_divider.AxesLocator` for
+        the specified cell.
 
         Parameters
         ----------
diff --git a/lib/mpl_toolkits/axes_grid1/axes_rgb.py b/lib/mpl_toolkits/axes_grid1/axes_rgb.py
@@ -6,7 +6,10 @@
 
 def make_rgb_axes(ax, pad=0.01, axes_class=None, add_all=True):
     """
-    pad : fraction of the axes height.
+    Parameters
+    ----------
+    pad : float
+        Fraction of the axes height.
     """
 
     divider = make_axes_locatable(ax)
diff --git a/lib/mpl_toolkits/axes_grid1/parasite_axes.py b/lib/mpl_toolkits/axes_grid1/parasite_axes.py
@@ -251,12 +251,11 @@ def pick(self, mouseevent):
 
     def twinx(self, axes_class=None):
         """
-        create a twin of Axes for generating a plot with a sharex
-        x-axis but independent y axis.  The y-axis of self will have
-        ticks on left and the returned axes will have ticks on the
-        right
-        """
+        Create a twin of Axes with a shared x-axis but independent y-axis.
 
+        The y-axis of self will have ticks on the left and the returned axes
+        will have ticks on the right.
+        """
         if axes_class is None:
             axes_class = self._get_base_axes()
 
@@ -280,12 +279,11 @@ def _remove_twinx(self, ax):
 
     def twiny(self, axes_class=None):
         """
-        create a twin of Axes for generating a plot with a shared
-        y-axis but independent x axis.  The x-axis of self will have
-        ticks on bottom and the returned axes will have ticks on the
-        top
-        """
+        Create a twin of Axes with a shared y-axis but independent x-axis.
 
+        The x-axis of self will have ticks on the bottom and the returned axes
+        will have ticks on the top.
+        """
         if axes_class is None:
             axes_class = self._get_base_axes()
 
@@ -309,12 +307,11 @@ def _remove_twiny(self, ax):
 
     def twin(self, aux_trans=None, axes_class=None):
         """
-        create a twin of Axes for generating a plot with a sharex
-        x-axis but independent y axis.  The y-axis of self will have
-        ticks on left and the returned axes will have ticks on the
-        right
-        """
+        Create a twin of Axes with no shared axis.
 
+        While self will have ticks on the left and bottom axis, the returned
+        axes will have ticks on the top and right axis.
+        """
         if axes_class is None:
             axes_class = self._get_base_axes()
 
