DOC: Improved the docstring of pandas.plotting._core.FramePlotMethods…
….barh()

- Added examples section
- Added extended summary
- Added argument explanation

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.plotting._core.FramePlotMethods.barh)  ###########
################################################################################

Make a horizontal bar plot.

A horizontal bar plot is a plot that presents categorical data with
rectangular bars with lengths proportional to the values that they
represent. A bar plot shows comparisons among discrete categories. One
axis of the plot shows the specific categories being compared, and the
other axis represents a measured value.

Parameters
----------
x : label or position, optional
    Column to be used for categories.
y : label or position, optional
    Columns to be plotted from the DataFrame.
kwds : optional
    Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`.

Returns
-------
axes : matplotlib.AxesSubplot or np.array of them

See Also
--------
pandas.DataFrame.plot.bar: Vertical bar plot
pandas.DataFrame.plot : Make plots of DataFrame using matplotlib.
matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib.

Examples
--------
Basic example

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]})
    >>> ax = df.plot.barh(x='lab',y='val')

Plot a whole DataFrame to a horizontal bar plot

.. plot::
    :context: close-figs

    >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
    >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
    >>> index = ['snail', 'pig', 'elephant',
    ...          'rabbit', 'giraffe', 'coyote', 'horse']
    >>> df = pd.DataFrame({'speed': speed,
    ...                    'lifespan': lifespan}, index=index)
    >>> ax = df.plot.barh()

Plot a column of the DataFrame to a horizontal bar plot

.. plot::
    :context: close-figs

    >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
    >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
    >>> index = ['snail', 'pig', 'elephant',
    ...          'rabbit', 'giraffe', 'coyote', 'horse']
    >>> df = pd.DataFrame({'speed': speed,
    ...                    'lifespan': lifespan}, index=index)
    >>> ax = df.plot.barh(y='speed')

Plot DataFrame versus the desired column

.. plot::
    :context: close-figs

    >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
    >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
    >>> index = ['snail', 'pig', 'elephant',
    ...          'rabbit', 'giraffe', 'coyote', 'horse']
    >>> df = pd.DataFrame({'speed': speed,
    ...                    'lifespan': lifespan}, index=index)
    >>> ax = df.plot.barh(x='lifespan')

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.plotting._core.FramePlotMethods.barh" correct. :)

```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry
