DOC: Improved the docstring of pandas.plotting._core.FramePlotMethods…
State: closed

….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


Labels:
name: Docs
name: Visualization
description: plotting

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20157?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@0780193`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #20157   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45074           
  Misses            ?     4078           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.08% <ø> (?)` | |
| #single | `41.84% <ø> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20157?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20157/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.23% <ø> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20157?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/20157?src=pr&el=footer). Last update [0780193...3abe837](https://codecov.io/gh/pandas-dev/pandas/pull/20157?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks!