Cleanup image docs

timhoffm · timhoffm · commit 6c6732fd13b5 · 2020-01-17T03:07:29.000+01:00
diff --git a/lib/matplotlib/image.py b/lib/matplotlib/image.py
@@ -70,7 +70,7 @@ def composite_images(images, renderer, magnification=1.0):
 
     renderer : `.RendererBase`
 
-    magnification : float
+    magnification : float, default: 1
         The additional magnification to apply for the renderer in use.
 
     Returns
@@ -303,8 +303,7 @@ def _get_scalar_alpha(self):
 
     def changed(self):
         """
-        Call this whenever the mappable is changed so observers can
-        update state
+        Call this whenever the mappable is changed so observers can update.
         """
         self._imcache = None
         self._rgbacache = None
@@ -627,9 +626,7 @@ def draw(self, renderer, *args, **kwargs):
         self.stale = False
 
     def contains(self, mouseevent):
-        """
-        Test whether the mouse event occurred within the image.
-        """
+        """Test whether the mouse event occurred within the image."""
         inside, info = self._default_contains(mouseevent)
         if inside is not None:
             return inside, info
@@ -659,7 +656,7 @@ def contains(self, mouseevent):
         return inside, {}
 
     def write_png(self, fname):
-        """Write the image to png file with fname"""
+        """Write the image to png file *fname*."""
         im = self.to_rgba(self._A[::-1] if self.origin == 'lower' else self._A,
                           bytes=True, norm=True)
         PIL.Image.fromarray(im).save(fname, format="png")
@@ -733,15 +730,14 @@ def get_interpolation(self):
         'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric',
         'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos',
         or 'none'.
-
         """
         return self._interpolation
 
     def set_interpolation(self, s):
         """
         Set the interpolation method the image uses when resizing.
 
-        if None, use a value from rc setting. If 'none', the image is
+        If None, use :rc:`image.interpolation`. If 'none', the image is
         shown as is without interpolating. 'none' is only supported in
         agg, ps and pdf backends and will fall back to 'nearest' mode
         for other backends.
@@ -750,8 +746,7 @@ def set_interpolation(self, s):
         ----------
         s : {'antialiased', 'nearest', 'bilinear', 'bicubic', 'spline16',
 'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric', 'catrom', \
-'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'}
-
+'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos', 'none'} or None
         """
         if s is None:
             s = rcParams['image.interpolation']
@@ -775,7 +770,7 @@ def set_resample(self, v):
         Parameters
         ----------
         v : bool or None
-            If None, use :rc:`image.resample` = True.
+            If None, use :rc:`image.resample`.
         """
         if v is None:
             v = rcParams['image.resample']
@@ -862,7 +857,6 @@ class AxesImage(_ImageBase):
         When True, use a full resampling method. When False, only resample when
         the output image is larger than the input image.
     **kwargs : `.Artist` properties
-
     """
     def __str__(self):
         return "AxesImage(%g,%g;%gx%g)" % tuple(self.axes.bbox.bounds)
@@ -911,9 +905,7 @@ def make_image(self, renderer, magnification=1.0, unsampled=False):
             magnification, unsampled=unsampled)
 
     def _check_unsampled_image(self, renderer):
-        """
-        Return whether the image would be better drawn unsampled.
-        """
+        """Return whether the image would be better drawn unsampled."""
         return (self.get_interpolation() == "none"
                 and renderer.option_scale_image())
 
@@ -999,7 +991,7 @@ def __init__(self, ax, *, interpolation='nearest', **kwargs):
         """
         Parameters
         ----------
-        interpolation : {'nearest', 'bilinear'}
+        interpolation : {'nearest', 'bilinear'}, default: 'nearest'
 
         **kwargs
             All other keyword arguments are identical to those of `.AxesImage`.
@@ -1091,8 +1083,8 @@ def set_interpolation(self, s):
         """
         Parameters
         ----------
-        s : str, None
-            Either 'nearest', 'bilinear', or ``None``.
+        s : {'nearest', 'bilinear'} or None
+            If None, use :rc:`image.interpolation`.
         """
         if s is not None and s not in ('nearest', 'bilinear'):
             raise NotImplementedError('Only nearest neighbor and '
@@ -1137,12 +1129,28 @@ def __init__(self, ax,
                  **kwargs
                  ):
         """
-        cmap defaults to its rc setting
-
-        cmap is a colors.Colormap instance
-        norm is a colors.Normalize instance to map luminance to 0-1
-
-        Additional kwargs are matplotlib.artist properties
+        Parameters
+        ----------
+        ax : `~.axes.Axes`
+            The axes the image will belong to.
+        x, y : 1D array-like, optional
+            Monotonic arrays of length N+1 and M+1, respectively, specifying
+            rectangle boundaries.  If not given, will default to
+            ``range(N + 1)`` and ``range(M + 1)``, respectively.
+        A : array-like
+            The data to be color-coded. The interpretation depends on the
+            shape:
+
+            - (M, N) ndarray or masked array: values to be colormapped
+            - (M, N, 3): RGB array
+            - (M, N, 4): RGBA array
+
+        cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
+            The Colormap instance or registered colormap name used to map
+            scalar data to colors.
+        norm : `~matplotlib.colors.Normalize`
+            Maps luminance to 0-1.
+        **kwargs : `.Artist` properties
         """
         super().__init__(ax, norm=norm, cmap=cmap)
         self.update(kwargs)
@@ -1192,13 +1200,17 @@ def set_data(self, x, y, A):
 
         Parameters
         ----------
-        x, y : 1D array-likes or None
-            Monotonic arrays of shapes (N + 1,) and (M + 1,), respectively,
-            specifying rectangle boundaries.  If None, will default to
+        x, y : 1D array-like, optional
+            Monotonic arrays of length N+1 and M+1, respectively, specifying
+            rectangle boundaries.  If not given, will default to
             ``range(N + 1)`` and ``range(M + 1)``, respectively.
         A : array-like
-            (M, N) ndarray or masked array of values to be colormapped, or
-            (M, N, 3) RGB array, or (M, N, 4) RGBA array.
+            The data to be color-coded. The interpretation depends on the
+            shape:
+
+            - (M, N) ndarray or masked array: values to be colormapped
+            - (M, N, 3): RGB array
+            - (M, N, 4): RGBA array
         """
         A = cbook.safe_masked_invalid(A, copy=True)
         if x is None:
@@ -1473,17 +1485,15 @@ def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None,
         values that map to the colormap color limits. If either *vmin*
         or *vmax* is None, that limit is determined from the *arr*
         min/max value.
-    cmap : str or `~matplotlib.colors.Colormap`, optional
+    cmap : str or `~matplotlib.colors.Colormap`, default: :rc:`image.cmap`
         A Colormap instance or registered colormap name. The colormap
         maps scalar data to colors. It is ignored for RGB(A) data.
-        Defaults to :rc:`image.cmap` ('viridis').
     format : str, optional
         The file format, e.g. 'png', 'pdf', 'svg', ...  The behavior when this
         is unset is documented under *fname*.
-    origin : {'upper', 'lower'}, optional
+    origin : {'upper', 'lower'}, default: :rc:`image.origin`
         Indicates whether the ``(0, 0)`` index of the array is in the upper
-        left or lower left corner of the axes.  Defaults to :rc:`image.origin`
-        ('upper').
+        left or lower left corner of the axes.
     dpi : int
         The DPI to store in the metadata of the file.  This does not affect the
         resolution of the output image.
@@ -1547,7 +1557,8 @@ def imsave(fname, arr, vmin=None, vmax=None, cmap=None, format=None,
 
 
 def pil_to_array(pilImage):
-    """Load a `PIL image`_ and return it as a numpy int array.
+    """
+    Load a `PIL image`_ and return it as a numpy int array.
 
     .. _PIL image: https://pillow.readthedocs.io/en/latest/reference/Image.html
 
@@ -1629,14 +1640,14 @@ def thumbnail(infile, thumbfile, scale=0.1, interpolation='bilinear',
     thumbfile : str or file-like
         The thumbnail filename.
 
-    scale : float, optional
+    scale : float, default: 0.1
         The scale factor for the thumbnail.
 
-    interpolation : str, optional
+    interpolation : str, default: 'bilinear'
         The interpolation scheme used in the resampling. See the
         *interpolation* parameter of `~.Axes.imshow` for possible values.
 
-    preview : bool, optional
+    preview : bool, default: False
         If True, the default backend (presumably a user interface
         backend) will be used which will cause a figure to be raised if
         `~matplotlib.pyplot.show` is called.  If it is False, the figure is
