DOC: update the pandas.DataFrame.plot.bar docsctring
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.bar)  ####################
################################################################################

Vertical bar plot.

A 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, default None
    Allows plotting of one column versus another.
y : label or position, default None
    Allows plotting of one column versus another.
**kwds : optional
    Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`.

Returns
-------
axes : matplotlib.AxesSubplot or np.array of them

Examples
--------

Basic plot

.. plot::
    :context: close-figs

    >>> df = pd.DataFrame({'lab':['A','B','C'], 'val':[10,30,20]})
    >>> ax = df.plot.bar(x='lab',y='val')

Plot a whole dataframe to a 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.bar()

Plot a column of the dataframe to a 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.bar(y='speed')

Plot only selected categories for the dataframe

.. 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.bar(x='lifespan')

See Also
--------
pandas.DataFrame.plot.barh : Horizontal bar plot.
pandas.DataFrame.plot : Make plots of DataFrame using matplotlib.
matplotlib.pyplot.bar : Make a bar plot.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'**kwds'}

```

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.

Small issue with **kwds docstring


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20158?src=pr&el=h1) Report
> Merging [#20158](https://codecov.io/gh/pandas-dev/pandas/pull/20158?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/31afaf858604ab85665b54b92f40cef19d69a28d?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

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

```diff
@@           Coverage Diff           @@
##           master   #20158   +/-   ##
=======================================
  Coverage   91.72%   91.72%           
=======================================
  Files         150      150           
  Lines       49165    49165           
=======================================
  Hits        45099    45099           
  Misses       4066     4066
```

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

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

------

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

Does it look good now?
Thanks for the PR! 
Welcome to check in a few hours if everything looks OK at http://pandas-docs.github.io/pandas-docs-travis/generated/pandas.DataFrame.plot.bar.html#pandas.DataFrame.plot.bar