DOC: update the pandas.DataFrame.plot.hist docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
#################### Docstring (pandas.DataFrame.plot.hist) ####################
################################################################################

Draw one histogram of the DataFrame's Series using matplotlib.

A histogram is a representation of the distribution of data.
This function groups the values of all given Series in the DataFrame
into bins, and draws all bins in only one matplotlib.AxesSubplot. This
is useful when the DataFrame's Series are in a similar scale.

Parameters
----------
by : str
    Column in the DataFrame to group by.
bins : int, default 10
    Number of histogram bins to be used.
**kwds : optional
    Parameters to pass on to :meth:`pandas.DataFrame.plot`.

Returns
-------
axes : matplotlib.AxesSubplot or np.array of them

See Also
--------
:meth:`pandas.DataFrame.hist` : Draw histograms per DataFrame's Series.
:meth:`pandas.Series.hist` : Draw a histogram with Series' data.

Examples
--------

When using values between 0 and 3, calling hist() with bins = 3 will
create three bins: one that groups values between 0 and 1, another
for values between 1 and 2, and another for values between 2 and 3.
We use alpha parameter to be able to see overlapping columns.

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame({
    ...     'length': [ 1.5, 0.5, 1.2, 0.9, 3],
    ...     'width': [ 0.7, 0.2, 0.15, 0.2,  1.1]
    ...     }, index= ['pig', 'rabbit', 'duck', 'chicken', 'horse'])
    >>> hist = df.plot.hist(bins = 3, xticks = range(4), alpha = 0.5)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.plot.hist" correct. :)


```


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20155?src=pr&el=h1) Report
> Merging [#20155](https://codecov.io/gh/pandas-dev/pandas/pull/20155?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/7273ea0709590e6264607f227bb8def0ef656c50?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/20155/graphs/tree.svg?height=150&token=eZ4WkYLtcO&width=650&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20155?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20155      +/-   ##
==========================================
+ Coverage   91.77%   91.79%   +0.02%     
==========================================
  Files         152      152              
  Lines       49205    49205              
==========================================
+ Hits        45159    45169      +10     
+ Misses       4046     4036      -10
```

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

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20155?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20155/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.27% <ø> (ø)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20155/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `83.74% <0%> (-0.21%)` | :arrow_down: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20155/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.68% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/20155/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy90aW1lZGVsdGFzLnB5) | `91.22% <0%> (ø)` | :arrow_up: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20155/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/20155?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/20155?src=pr&el=footer). Last update [7273ea0...627170e](https://codecov.io/gh/pandas-dev/pandas/pull/20155?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Hello @liopic! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 19, 2018 at 20:56 Hours UTC
@liopic Thanks for the PR :+1: