DOC: updated docstrings for FramePlotMethods and SeriesPlotMethods
State: closed

Closes #15458


Labels:
name: Docs

Comments:
@yinleon I don't think we will want to duplicate the full docstring.

I don't think our decorator will work with a class docstring, but what you can also do is something like:

```
class SeriesPlotMethods
    ....

SeriesPlotMethods.__doc__ = _shared_docs['plot'] % _shared_doc_series_kwargs
```

to reuse the existing docs.

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/15611?src=pr&el=h1) Report
> Merging [#15611](https://codecov.io/gh/pandas-dev/pandas/pull/15611?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/9da0e0b233c79311c19dad6b151a157c4e47e109?src=pr&el=desc) will **decrease** coverage by `-0.03%`.
> The diff coverage is `n/a`.


```diff
@@            Coverage Diff             @@
##           master   #15611      +/-   ##
==========================================
- Coverage   91.02%   90.99%   -0.03%     
==========================================
  Files         143      143              
  Lines       49295    49295              
==========================================
- Hits        44869    44857      -12     
- Misses       4426     4438      +12
```


| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/15611?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/tools/plotting.py](https://codecov.io/gh/pandas-dev/pandas/compare/9da0e0b233c79311c19dad6b151a157c4e47e109...a6cf974abdcf96a3663e9664bdfdc4550f2dffa0?src=pr&el=tree#diff-cGFuZGFzL3Rvb2xzL3Bsb3R0aW5nLnB5) | `71.79% <ø> (ø)` | :white_check_mark: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/compare/9da0e0b233c79311c19dad6b151a157c4e47e109...a6cf974abdcf96a3663e9664bdfdc4550f2dffa0?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :x: |
| [pandas/tools/merge.py](https://codecov.io/gh/pandas-dev/pandas/compare/9da0e0b233c79311c19dad6b151a157c4e47e109...a6cf974abdcf96a3663e9664bdfdc4550f2dffa0?src=pr&el=tree#diff-cGFuZGFzL3Rvb2xzL21lcmdlLnB5) | `91.76% <0%> (-0.35%)` | :x: |
| [pandas/core/common.py](https://codecov.io/gh/pandas-dev/pandas/compare/9da0e0b233c79311c19dad6b151a157c4e47e109...a6cf974abdcf96a3663e9664bdfdc4550f2dffa0?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY29tbW9uLnB5) | `90.96% <0%> (-0.34%)` | :x: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/compare/9da0e0b233c79311c19dad6b151a157c4e47e109...a6cf974abdcf96a3663e9664bdfdc4550f2dffa0?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.87% <0%> (-0.1%)` | :x: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/15611?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/15611?src=pr&el=footer). Last update [9da0e0b...aa09f91](https://codecov.io/gh/pandas-dev/pandas/compare/9da0e0b233c79311c19dad6b151a157c4e47e109...aa09f91f6dc7aeecfa1f4f683d47f605a5aeed96?el=footer&src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).
Thanks for the tip @jorisvandenbossche! I made the requested changes in commit `aa09f91`. I was told to rebase commits on another project, and can do so if requested.

Edit: I missed this

> I don't think our decorator will work with a class docstring
Hmm, this approach also does not seem to work (didn't know that):

```
  File "/home/travis/build/pandas-dev/pandas/pandas/tools/plotting.py", line 3766, in <module>
    SeriesPlotMethods.__doc__ = _shared_docs['plot'] % _shared_doc_series_kwargs
AttributeError: attribute '__doc__' of 'type' objects is not writable
```

This only errors on Python 2, but you normally can do this assignment in the class definition as well

like 

```
class ..

    __doc__ = _shared_docs['plot']

```

@yinleon Do you have time to update this?
@yinleon can you rebase / update
closing as stale