DOC: Update docstring to numpy format for last few functions in transforms (#9309)

TomDonoghue · tacaswell · commit 8f9a2083db8f · 2017-10-08T15:47:04.000-04:00
* DOC: Update docstring to numpy format for last few functions

* DOC: fix syntax for arguments, add class links, improve wording.

* DOC: Update link to class in local file
diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py
@@ -2866,31 +2866,33 @@ def _revalidate(self):
 
 
 def nonsingular(vmin, vmax, expander=0.001, tiny=1e-15, increasing=True):
-    '''
+    """
     Modify the endpoints of a range as needed to avoid singularities.
 
-    *vmin*, *vmax*
-        the initial endpoints.
-
-    *tiny*
-        threshold for the ratio of the interval to the maximum absolute
+    Parameters
+    ----------
+    vmin, vmax : float
+        The initial endpoints.
+    expander : float, optional, default: 0.001
+        Fractional amount by which *vmin* and *vmax* are expanded if
+        the original interval is too small, based on *tiny*.
+    tiny : float, optional, default: 1e-15
+        Threshold for the ratio of the interval to the maximum absolute
         value of its endpoints.  If the interval is smaller than
         this, it will be expanded.  This value should be around
         1e-15 or larger; otherwise the interval will be approaching
         the double precision resolution limit.
+    increasing : bool, optional, default: True
+        If True, swap *vmin*, *vmax* if *vmin* > *vmax*.
+
+    Returns
+    -------
+    vmin, vmax : float
+        Endpoints, expanded and/or swapped if necessary.
+        If either input is inf or NaN, or if both inputs are 0 or very
+        close to zero, it returns -*expander*, *expander*.
+    """
 
-    *expander*
-        fractional amount by which *vmin* and *vmax* are expanded if
-        the original interval is too small, based on *tiny*.
-
-    *increasing*: [True | False]
-        If True (default), swap *vmin*, *vmax* if *vmin* > *vmax*
-
-    Returns *vmin*, *vmax*, expanded and/or swapped if necessary.
-
-    If either input is inf or NaN, or if both inputs are 0 or very
-    close to zero, it returns -*expander*, *expander*.
-    '''
     if (not np.isfinite(vmin)) or (not np.isfinite(vmax)):
         return -expander, expander
 
@@ -2918,25 +2920,65 @@ def nonsingular(vmin, vmax, expander=0.001, tiny=1e-15, increasing=True):
 
 
 def interval_contains(interval, val):
+    """
+    Check, inclusively, whether an interval includes a given value.
+
+    Parameters
+    ----------
+    interval : sequence of scalar
+        A 2-length sequence, endpoints that define the interval.
+    val : scalar
+        Value to check is within interval.
+
+    Returns
+    -------
+    bool
+        Returns true if given val is within the interval.
+    """
     a, b = interval
     return a <= val <= b or a >= val >= b
 
 
 def interval_contains_open(interval, val):
+    """
+    Check, excluding endpoints, whether an interval includes a given value.
+
+    Parameters
+    ----------
+    interval : sequence of scalar
+        A 2-length sequence, endpoints that define the interval.
+    val : scalar
+        Value to check is within interval.
+
+    Returns
+    -------
+    bool
+        Returns true if given val is within the interval.
+    """
     a, b = interval
     return a < val < b or a > val > b
 
 
 def offset_copy(trans, fig=None, x=0.0, y=0.0, units='inches'):
-    '''
+    """
     Return a new transform with an added offset.
-      args:
-        trans is any transform
-      kwargs:
-        fig is the current figure; it can be None if units are 'dots'
-        x, y give the offset
-        units is 'inches', 'points' or 'dots'
-    '''
+
+    Parameters
+    ----------
+    trans : :class:`Transform` instance
+        Any transform, to which offset will be applied.
+    fig : :class:`~matplotlib.figure.Figure`, optional, default: None
+        Current figure. It can be None if *units* are 'dots'.
+    x, y : float, optional, default: 0.0
+        Specifies the offset to apply.
+    units : {'inches', 'points', 'dots'}, optional
+        Units of the offset.
+
+    Returns
+    -------
+    trans : :class:`Transform` instance
+        Transform with applied offset.
+    """
     if units == 'dots':
         return trans + Affine2D().translate(x, y)
     if fig is None:
