DOC: Fixed example & description for pandas.cut
State: closed

- [ ] closes #xxxx
- [ ] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

```
################################################################################
############################ Docstring (pandas.cut) ############################
################################################################################

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 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 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, 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 : 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
-----
Any NA values will be NA in the result. Out of bounds values will be NA in
the resulting pandas.Categorical object.

Examples
--------
>>> pd.cut(np.array([.2, 1.4, 2.5, 6.2, 9.7, 2.1]), 3, retbins=True)
... # doctest: +ELLIPSIS
([(0.19, 3.367], (0.19, 3.367], (0.19, 3.367], (3.367, 6.533], ...
Categories (3, interval[float64]): [(0.19, 3.367] < (3.367, 6.533] ...

>>> pd.cut(np.array([.2, 1.4, 2.5, 6.2, 9.7, 2.1]),
...        3, labels=["good", "medium", "bad"])
... # doctest: +SKIP
[good, good, good, medium, bad, good]
Categories (3, object): [good < medium < bad]

>>> pd.cut(np.ones(5), 4, labels=False)
array([1, 1, 1, 1, 1], dtype=int64)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.cut" correct. :)
```

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=h1) Report
> Merging [#20069](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/1d73cf33b4ac5feac9adc3feab0e13518dd0d154?src=pr&el=desc) will **increase** coverage by `0.02%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20069/graphs/tree.svg?token=eZ4WkYLtcO&width=650&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20069      +/-   ##
==========================================
+ Coverage   91.69%   91.72%   +0.02%     
==========================================
  Files         150      150              
  Lines       49112    49112              
==========================================
+ Hits        45035    45047      +12     
+ Misses       4077     4065      -12
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.1% <ø> (+0.02%)` | :arrow_up: |
| #single | `41.86% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/reshape/tile.py](https://codecov.io/gh/pandas-dev/pandas/pull/20069/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS90aWxlLnB5) | `92.94% <ø> (ø)` | :arrow_up: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20069/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `66.81% <0%> (+1.73%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=footer). Last update [1d73cf3...db337c1](https://codecov.io/gh/pandas-dev/pandas/pull/20069?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Hello @ikoevska! Thanks for updating the PR.







 - In the file [`pandas/core/indexes/base.py`](https://github.com/pandas-dev/pandas/blob/db337c18066e3711ea1817030cf60aa4ba33ec7a/pandas/core/indexes/base.py), following are the PEP8 issues :

> [Line 1159:15](https://github.com/pandas-dev/pandas/blob/db337c18066e3711ea1817030cf60aa4ba33ec7a/pandas/core/indexes/base.py#L1159): [W291](https://duckduckgo.com/?q=pep8%20W291) trailing whitespace
































I am closing this one as it got totally messed up after a rebase. Will open a new one with @jorisvandenbossche comments applied.
@ikoevska For future reference, please update this PR. Even if you make a new branch locally, you can force push to the same branch on your fork, and this PR gets updated. But no problem for this time!