DOC: update the pandas.DataFrame.clip_lower docstring

pandas/core/generic.py

@@ -5716,24 +5716,81 @@ def clip_upper(self, threshold, axis=None, inplace=False):
 
     def clip_lower(self, threshold, axis=None, inplace=False):
         """
-        Return copy of the input with values below given value(s) truncated.
+        Trim the caller's values below a given `threshold`.
+
+        Elements below the `threshold` will be changed to match the
+        `threshold` value(s).
 
         Parameters
         ----------
-        threshold : float or array_like
-        axis : int or string axis name, optional
+        threshold : float or array-like
+            Lower value(s) to which the input value(s) will be trimmed.
+        axis : {0 or 'index', 1 or 'columns', None}, default None
             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
+            Whether to perform the operation in place on the data.
+
+            .. versionadded:: 0.21.0
 
         See Also
         --------
-        clip
+        DataFrame.clip : General purpose method to trim `DataFrame` values to
+            given threshold(s)
+        DataFrame.clip_upper : Trim `DataFrame` values above given
+            threshold(s)
+        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 : same type as input
+        type of caller
+            Original data with values trimmed.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'a': [-1, -2, -100],
+        ...                    'b': [1, 2, 100]},
+        ...                    index = ['foo', 'bar', 'foobar'])
+
+        >>> df
+                  a    b
+        foo      -1    1
+        bar      -2    2
+        foobar -100  100
+
+        Clip to a scalar value
+
+        >>> df.clip_lower(0)
+                a    b
+        foo     0    1
+        bar     0    2
+        foobar  0  100
+
+        Clip to an array along the index axis
+
+        >>> df.clip_lower([0, 5, 10], axis=0)
+                 a    b
+        foo      0    1
+        bar      5    5
+        foobar  10  100
+
+        Clip to an array along the column axis
+
+        >>> df.clip_lower([-5, 10], axis=1)
+                a    b
+        foo    -1   10
+        bar    -2   10
+        foobar -5  100
+
+        Clip in place
+
+        >>> df.clip_lower(0, inplace=True)
+        >>> df
+                a    b
+        foo     0    1
+        bar     0    2
+        foobar  0  100
         """
         return self._clip_with_one_bound(threshold, method=self.ge,
                                          axis=axis, inplace=inplace)