DOC: Update docs for pandas.cut

Author: ikoevska

pandas/core/reshape/tile.py

@@ -26,53 +26,64 @@
 def cut(x, bins, right=True, labels=None, retbins=False, precision=3,
         include_lowest=False):
     """
-    Return indices of half-open bins to which each value of `x` belongs.
+    Return indices of half-open `bins` to which each value of `x` belongs.
+
+    Use `cut` when you need to segment and sort data values into bins or
+    buckets of data. This function is also useful for going from a continuous
+    variable to a categorical variable. For example, `cut` could convert ages
+    to groups of age ranges.
 
     Parameters
     ----------
     x : array-like
         Input array to be binned. It has to be 1-dimensional.
-    bins : int, sequence of scalars, or IntervalIndex
-        If `bins` is an int, it defines the number of equal-width bins in the
-        range of `x`. However, in this case, the range of `x` is extended
-        by .1% on each side to include the min or max values of `x`. If
-        `bins` is a sequence it defines the bin edges allowing for
-        non-uniform bin width. No extension of the range of `x` is done in
-        this case.
-    right : bool, optional
-        Indicates whether the bins include the rightmost edge or not. If
-        right == True (the default), then the bins [1,2,3,4] indicate
+    bins : int, sequence of scalars, or pandas.IntervalIndex
+        If `bins` is an int, defines the number of equal-width bins in the
+        range of `x`. The range of `x` is extended by .1% on each side to
+        include the min or max values of `x`.
+        If `bins` is a sequence, defines the bin edges allowing for
+        non-uniform bin width. No extension of the range of `x` is done.
+    right : bool, optional, default 'True'
+        Indicates whether the `bins` include the rightmost edge or not. If
+        `right == True` (the default), then the `bins` [1,2,3,4] indicate
         (1,2], (2,3], (3,4].
-    labels : array or boolean, default None
-        Used as labels for the resulting bins. Must be of the same length as
-        the resulting bins. If False, return only integer indicators of the
-        bins.
-    retbins : bool, optional
-        Whether to return the bins or not. Can be useful if bins is given
+    labels : array or bool, optional
+        Used as labels for the resulting `bins`. Must be of the same length as
+        the resulting `bins`. If False, returns only integer indicators of the
+        `bins`.
+    retbins : bool, optional, default 'False'
+        Whether to return the `bins` or not. Useful when `bins` is provided
         as a scalar.
-    precision : int, optional
-        The precision at which to store and display the bins labels
-    include_lowest : bool, optional
+    precision : int, optional, default '3'
+        The precision at which to store and display the `bins` labels.
+    include_lowest : bool, optional, default 'False'
         Whether the first interval should be left-inclusive or not.
 
     Returns
     -------
-    out : Categorical or Series or array of integers if labels is False
-        The return type (Categorical or Series) depends on the input: a Series
-        of type category if input is a Series else Categorical. Bins are
-        represented as categories when categorical data is returned.
-    bins : ndarray of floats
-        Returned only if `retbins` is True.
+    out : pandas.Categorical or Series, or array of int if `labels` is 'False'
+        The return type depends on the input.
+        If the input is a Series, a Series of type category is returned.
+        Else - pandas.Categorical is returned. `Bins` are represented as
+        categories when categorical data is returned.
+    bins : numpy.ndarray of floats
+        Returned only if `retbins` is 'True'.
+
+    See Also
+    --------
+    qcut : Discretize variable into equal-sized buckets based on rank
+        or based on sample quantiles.
+    pandas.Categorical : Represents a categorical variable in
+        classic R / S-plus fashion.
+    Series : One-dimensional ndarray with axis labels (including time series).
+    pandas.IntervalIndex : Immutable Index implementing an ordered,
+        sliceable set. IntervalIndex represents an Index of intervals that
+        are all closed on the same side.
 
     Notes
     -----
-    The `cut` function can be useful for going from a continuous variable to
-    a categorical variable. For example, `cut` could convert ages to groups
-    of age ranges.
-
-    Any NA values will be NA in the result.  Out of bounds values will be NA in
-    the resulting Categorical object
-
+    Any NA values will be NA in the result. Out of bounds values will be NA in
+    the resulting pandas.Categorical object.
 
     Examples
     --------
@@ -88,7 +99,7 @@ def cut(x, bins, right=True, labels=None, retbins=False, precision=3,
     Categories (3, object): [good < medium < bad]
 
     >>> pd.cut(np.ones(5), 4, labels=False)
-    array([1, 1, 1, 1, 1])
+    array([1, 1, 1, 1, 1], dtype=int64)
     """
     # NOTE: this binning code is changed a bit from histogram for var(x) == 0