DOC: consolidate clip_upper and clip_lower docstrings (#21812)

Author: jorisvandenbossche

pandas/core/generic.py

@@ -6547,32 +6547,46 @@ def clip(self, lower=None, upper=None, axis=None, inplace=False,
 
     def clip_upper(self, threshold, axis=None, inplace=False):
         """
-        Return copy of the input with values above given value(s) truncated.
+        Trim values above a given threshold.
 
-        It truncates values above a certain threshold. Threshold can be a
-        single value or an array, in the latter case it performs the truncation
-        element-wise.
+        Elements above the `threshold` will be changed to match the
+        `threshold` value(s). Threshold can be a single value or an array,
+        in the latter case it performs the truncation element-wise.
 
         Parameters
         ----------
-        threshold : float or array-like
+        threshold : numeric or array-like
             Maximum value allowed. All values above threshold will be set to
             this value.
-        axis : int or string axis name, optional
-            Align object with threshold along the given axis.
+
+            * float : every value is compared to `threshold`.
+            * array-like : The shape of `threshold` should match the object
+              it's compared to. When `self` is a Series, `threshold` should be
+              the length. When `self` is a DataFrame, `threshold` should 2-D
+              and the same shape as `self` for ``axis=None``, or 1-D and the
+              same length as the axis being compared.
+
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Align object with `threshold` along the given axis.
         inplace : boolean, default False
             Whether to perform the operation in place on the data.
 
             .. versionadded:: 0.21.0
 
-        See Also
-        --------
-        clip : Return input copy with values below/above thresholds truncated.
-        clip_lower : Method to truncate values below given thresholds.
-
         Returns
         -------
-        clipped : same type as input
+        clipped
+            Original data with values trimmed.
+
+        See Also
+        --------
+        DataFrame.clip : General purpose method to trim DataFrame values to
+            given threshold(s)
+        DataFrame.clip_lower : Trim DataFrame values below given
+            threshold(s)
+        Series.clip : General purpose method to trim Series values to given
+            threshold(s)
+        Series.clip_lower : Trim Series values below given threshold(s)
 
         Examples
         --------
@@ -6613,7 +6627,8 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         Trim values below a given threshold.
 
         Elements below the `threshold` will be changed to match the
-        `threshold` value(s).
+        `threshold` value(s). Threshold can be a single value or an array,
+        in the latter case it performs the truncation element-wise.
 
         Parameters
         ----------
@@ -6636,20 +6651,20 @@ def clip_lower(self, threshold, axis=None, inplace=False):
 
             .. versionadded:: 0.21.0
 
+        Returns
+        -------
+        clipped
+            Original data with values trimmed.
+
         See Also
         --------
-        DataFrame.clip : General purpose method to trim `DataFrame` values to
+        DataFrame.clip : General purpose method to trim DataFrame values to
             given threshold(s)
-        DataFrame.clip_upper : Trim `DataFrame` values above given
+        DataFrame.clip_upper : Trim DataFrame values above given
             threshold(s)
-        Series.clip : General purpose method to trim `Series` values to given
+        Series.clip : General purpose method to trim Series values to given
             threshold(s)
-        Series.clip_upper : Trim `Series` values above given threshold(s)
-
-        Returns
-        -------
-        clipped
-            Original data with values trimmed.
+        Series.clip_upper : Trim Series values above given threshold(s)
 
         Examples
         --------
@@ -6716,7 +6731,6 @@ def clip_lower(self, threshold, axis=None, inplace=False):
         0  4  5
         1  4  5
         2  5  6
-
         """
         return self._clip_with_one_bound(threshold, method=self.ge,
                                          axis=axis, inplace=inplace)