Merge pull request matplotlib#21536 from anntzer/md

Reword margins docstrings, and fix bounds on zmargin values.

Author: timhoffm

lib/matplotlib/axes/_base.py

@@ -2618,14 +2618,13 @@ def set_xmargin(self, m):
         """
         Set padding of X data limits prior to autoscaling.
 
-        *m* times the data interval will be added to each
-        end of that interval before it is used in autoscaling.
-        For example, if your data is in the range [0, 2], a factor of
-        ``m = 0.1`` will result in a range [-0.2, 2.2].
+        *m* times the data interval will be added to each end of that interval
+        before it is used in autoscaling.  If *m* is negative, this will clip
+        the data range instead of expanding it.
 
-        Negative values -0.5 < m < 0 will result in clipping of the data range.
-        I.e. for a data range [0, 2], a factor of ``m = -0.1`` will result in
-        a range [0.2, 1.8].
+        For example, if your data is in the range [0, 2], a margin of 0.1 will
+        result in a range [-0.2, 2.2]; a margin of -0.1 will result in a range
+        of [0.2, 1.8].
 
         Parameters
         ----------
@@ -2641,14 +2640,13 @@ def set_ymargin(self, m):
         """
         Set padding of Y data limits prior to autoscaling.
 
-        *m* times the data interval will be added to each
-        end of that interval before it is used in autoscaling.
-        For example, if your data is in the range [0, 2], a factor of
-        ``m = 0.1`` will result in a range [-0.2, 2.2].
+        *m* times the data interval will be added to each end of that interval
+        before it is used in autoscaling.  If *m* is negative, this will clip
+        the data range instead of expanding it.
 
-        Negative values -0.5 < m < 0 will result in clipping of the data range.
-        I.e. for a data range [0, 2], a factor of ``m = -0.1`` will result in
-        a range [0.2, 1.8].
+        For example, if your data is in the range [0, 2], a margin of 0.1 will
+        result in a range [-0.2, 2.2]; a margin of -0.1 will result in a range
+        of [0.2, 1.8].
 
         Parameters
         ----------

lib/mpl_toolkits/mplot3d/axes3d.py

@@ -536,13 +536,20 @@ def set_zmargin(self, m):
         """
         Set padding of Z data limits prior to autoscaling.
 
-        *m* times the data interval will be added to each
-        end of that interval before it is used in autoscaling.
+        *m* times the data interval will be added to each end of that interval
+        before it is used in autoscaling.  If *m* is negative, this will clip
+        the data range instead of expanding it.
 
-        accepts: float in range 0 to 1
+        For example, if your data is in the range [0, 2], a margin of 0.1 will
+        result in a range [-0.2, 2.2]; a margin of -0.1 will result in a range
+        of [0.2, 1.8].
+
+        Parameters
+        ----------
+        m : float greater than -0.5
         """
-        if m < 0 or m > 1:
-            raise ValueError("margin must be in range 0 to 1")
+        if m <= -0.5:
+            raise ValueError("margin must be greater than -0.5")
         self._zmargin = m
         self._request_autoscale_view(scalex=False, scaley=False, scalez=True)
         self.stale = True