Merge pull request matplotlib#27279 from anntzer/d

Tweak a few docstrings.

Author: QuLogic

lib/matplotlib/axes/_axes.py

@@ -3007,11 +3007,10 @@ def stem(self, *args, linefmt=None, markerfmt=None, basefmt=None, bottom=0,
             A format string defining the properties of the baseline.
 
         orientation : {'vertical', 'horizontal'}, default: 'vertical'
-            If 'vertical', will produce a plot with stems oriented vertically,
-            If 'horizontal', the stems will be oriented horizontally.
+            The orientation of the stems.
 
         bottom : float, default: 0
-            The y/x-position of the baseline (depending on orientation).
+            The y/x-position of the baseline (depending on *orientation*).
 
         label : str, default: None
             The label to use for the stems in legends.

lib/matplotlib/colors.py

@@ -1245,21 +1245,19 @@ def __init__(self, vmin=None, vmax=None, clip=False):
             provided, they default to the minimum and maximum values of the input,
             respectively.
 
-
         clip : bool, default: False
             Determines the behavior for mapping values outside the range
             ``[vmin, vmax]``.
 
-            If *clip* is ``False``, values outside ``[vmin, vmax]`` are also transformed
-            linearly, leading to results outside ``[0, 1]``. For a standard use with
-            colormaps, this behavior is desired because colormaps mark these outside
-            values with specific colors for over or under.
-
-            If *clip* is ``True``, values outside ``[vmin, vmax]`` are set to 0 or 1,
-            depending on which boundary they're closer to. This makes these values
-            indistinguishable from regular boundary values and can lead to
-            misinterpretation of the data.
+            If clipping is off, values outside the range ``[vmin, vmax]`` are
+            also transformed, resulting in values outside ``[0, 1]``.  This
+            behavior is usually desirable, as colormaps can mark these *under*
+            and *over* values with specific colors.
 
+            If clipping is on, values below *vmin* are mapped to 0 and values
+            above *vmax* are mapped to 1. Such values become indistinguishable
+            from regular boundary values, which may cause misinterpretation of
+            the data.
 
         Notes
         -----
@@ -1567,15 +1565,15 @@ def __init__(self, vcenter=0, halfrange=None, clip=False):
             Determines the behavior for mapping values outside the range
             ``[vmin, vmax]``.
 
-            If clipping is off, values outside the range ``[vmin, vmax]`` are also
-            transformed, resulting in values outside ``[0, 1]``. For a
-            standard use with colormaps, this behavior is desired because colormaps
-            mark these outside values with specific colors for *over* or *under*.
+            If clipping is off, values outside the range ``[vmin, vmax]`` are
+            also transformed, resulting in values outside ``[0, 1]``.  This
+            behavior is usually desirable, as colormaps can mark these *under*
+            and *over* values with specific colors.
 
-            If ``True`` values falling outside the range ``[vmin, vmax]``,
-            are mapped to 0 or 1, whichever is closer. This makes these values
-            indistinguishable from regular boundary values and can lead to
-            misinterpretation of the data.
+            If clipping is on, values below *vmin* are mapped to 0 and values
+            above *vmax* are mapped to 1. Such values become indistinguishable
+            from regular boundary values, which may cause misinterpretation of
+            the data.
 
         Examples
         --------
@@ -1852,14 +1850,13 @@ def forward(values: array-like) -> array-like
         ``[vmin, vmax]``.
 
         If clipping is off, values outside the range ``[vmin, vmax]`` are also
-        transformed by the function, resulting in values outside ``[0, 1]``. For a
-        standard use with colormaps, this behavior is desired because colormaps
-        mark these outside values with specific colors for *over* or *under*.
-
-        If ``True`` values falling outside the range ``[vmin, vmax]``,
-        are mapped to 0 or 1, whichever is closer. This makes these values
-        indistinguishable from regular boundary values and can lead to
-        misinterpretation of the data.
+        transformed by the function, resulting in values outside ``[0, 1]``.
+        This behavior is usually desirable, as colormaps can mark these *under*
+        and *over* values with specific colors.
+
+        If clipping is on, values below *vmin* are mapped to 0 and values above
+        *vmax* are mapped to 1. Such values become indistinguishable from
+        regular boundary values, which may cause misinterpretation of the data.
     """
 
 
@@ -1957,14 +1954,13 @@ class PowerNorm(Normalize):
         ``[vmin, vmax]``.
 
         If clipping is off, values outside the range ``[vmin, vmax]`` are also
-        transformed by the power function, resulting in values outside ``[0, 1]``. For
-        a standard use with colormaps, this behavior is desired because colormaps
-        mark these outside values with specific colors for *over* or *under*.
-
-        If ``True`` values falling outside the range ``[vmin, vmax]``,
-        are mapped to 0 or 1, whichever is closer. This makes these values
-        indistinguishable from regular boundary values and can lead to
-        misinterpretation of the data.
+        transformed by the power function, resulting in values outside ``[0, 1]``.
+        This behavior is usually desirable, as colormaps can mark these *under*
+        and *over* values with specific colors.
+
+        If clipping is on, values below *vmin* are mapped to 0 and values above
+        *vmax* are mapped to 1. Such values become indistinguishable from
+        regular boundary values, which may cause misinterpretation of the data.
 
     Notes
     -----

lib/matplotlib/legend.py

@@ -194,7 +194,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
 
 edgecolor : "inherit" or color, default: :rc:`legend.edgecolor`
     The legend's background patch edge color.
-    If ``"inherit"``, use take :rc:`axes.edgecolor`.
+    If ``"inherit"``, use :rc:`axes.edgecolor`.
 
 mode : {"expand", None}
     If *mode* is set to ``"expand"`` the legend will be horizontally

lib/matplotlib/projections/polar.py

@@ -201,7 +201,7 @@ def __init__(self, axis=None, use_rmin=True,
             Axis associated with this transform. This is used to get the
             minimum radial limit.
         use_rmin : `bool`, optional
-            If ``True`` add the minimum radial axis limit after
+            If ``True``, add the minimum radial axis limit after
             transforming from Cartesian coordinates. *axis* must also be
             specified for this to take effect.
         """