Apply suggestions from code review

jklymak · timhoffm · web-flow · commit bd64bfc3e125 · 2024-07-08T13:22:31.000-07:00
Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
diff --git a/doc/api/next_api_changes/behavior/28061-JMK.rst b/doc/api/next_api_changes/behavior/28061-JMK.rst
@@ -1,22 +1,23 @@
-imshow *interpolation_stage* default changed to 'auto'
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``imshow`` *interpolation_stage* default changed to 'auto'
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The *interpolation_stage* keyword argument `~.Axes.imshow` has a new default
+The *interpolation_stage* parameter of  `~.Axes.imshow` has a new default
 value 'auto'.  For images that are up-sampled less than a factor of
 three or down-sampled, image interpolation will occur in 'rgba' space.  For images
-that are up-sampled by more than a factor of 3, then image interpolation occurs
+that are up-sampled by a factor of 3 or more, then image interpolation occurs
 in 'data' space.
 
 The previous default was 'data', so down-sampled images may change subtly with
 the new default.  However, the new default also avoids floating point artifacts
 at sharp boundaries in a colormap when down-sampling.
 
-The previous behavior can achieved by changing :rc:`image.interpolation_stage`.
+The previous behavior can achieved by setting the *interpolation_stage* parameter
+or :rc:`image.interpolation_stage` to 'data'.
 
 imshow default *interpolation* changed to 'auto'
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The *interpolation* keyword argument `~.Axes.imshow` has a new default
+The *interpolation* parameter of `~.Axes.imshow` has a new default
 value 'auto', changed from 'antialiased', for consistency with *interpolation_stage*
-and because the interpolation is only anti-aliasing during down-sampling.  The
-'antialiased' string still works, and behaves exactly the same as 'auto'.
+and because the interpolation is only anti-aliasing during down-sampling.  Passing
+'antialiased' still works, and behaves exactly the same as 'auto', but is discouraged.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -5833,13 +5833,17 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None,
             resize filter is controlled by the parameter *filternorm*.
 
         interpolation_stage : {'auto', 'data', 'rgba'}, default: 'auto'
-            If 'data', interpolation is carried out on the data provided by the user,
-            useful if interpolating between pixels during upsampling.
-            If 'rgba', the interpolation is carried out in RGBA-space after the
-            color-mapping has been applied, useful if downsampling and combining
-            pixels visually. The default 'auto' is appropriate for most
-            applications where 'rgba' is used when downsampling, or upsampling at a
-            rate less than 3, and 'data' is used when upsampling at a higher rate.
+            Supported values:
+            
+            - 'data': Interpolation is carried out on the data provided by the user
+              This is useful if interpolating between pixels during upsampling.
+            - 'rgba': The interpolation is carried out in RGBA-space after the
+              color-mapping has been applied. This is useful if downsampling and
+              combining pixels visually.
+            - 'auto': Select a suitable interpolation stage automatically. This uses
+              'rgba' when downsampling, or upsampling at a rate less than 3, and
+              'data' when upsampling at a higher rate.
+              
             See :doc:`/gallery/images_contours_and_fields/image_antialiasing` for
             a discussion of image antialiasing.
 
diff --git a/lib/matplotlib/tests/test_png.py b/lib/matplotlib/tests/test_png.py
@@ -20,7 +20,8 @@ def test_pngsuite():
         if data.ndim == 2:
             # keep grayscale images gray
             cmap = cm.gray
-        # use the old default data interpolation stage
+        # Using the old default data interpolation stage lets us
+        # continue to use the existing reference image
         plt.imshow(data, extent=(i, i + 1, 0, 1), cmap=cmap,
                    interpolation_stage='data')
 
