DOC: Improve replace docstring
State: closed

xref #17673
closes #13852
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

I have tried to separate the docstrings for series and dataframe as suggested in the original issue but can try to combine them if that works better.

As noted in the original issue, ``replace`` can do a lot things and I've tried to cover most of them with the examples but would welcome other suggestions.

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=h1) Report
> Merging [#18100](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/86e9dcc164760c5197438968151b2b852647de84?src=pr&el=desc) will **decrease** coverage by `0.1%`.
> The diff coverage is `67.79%`.

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

```diff
@@            Coverage Diff             @@
##           master   #18100      +/-   ##
==========================================
- Coverage   91.25%   91.14%   -0.11%     
==========================================
  Files         163      163              
  Lines       50120    50225     +105     
==========================================
+ Hits        45737    45780      +43     
- Misses       4383     4445      +62
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.96% <67.79%> (-0.09%)` | :arrow_down: |
| #single | `40.24% <12.99%> (-0.14%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `91.7% <ø> (-0.73%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `91.92% <55.05%> (-3.09%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.05% <80.68%> (-0.81%)` | :arrow_down: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `65.2% <0%> (+1.81%)` | :arrow_up: |

------

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

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=h1) Report
> Merging [#18100](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/3f3b4e0bc15107153167ec605b45676113ffb9c1?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #18100      +/-   ##
==========================================
+ Coverage   91.62%   91.62%   +<.01%     
==========================================
  Files         150      150              
  Lines       48681    48689       +8     
==========================================
+ Hits        44604    44612       +8     
  Misses       4077     4077
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.99% <100%> (ø)` | :arrow_up: |
| #single | `41.74% <88.88%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/18100?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.91% <100%> (ø)` | :arrow_up: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.42% <100%> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/18100/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `94.61% <100%> (+0.01%)` | :arrow_up: |

------

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

@TomAugspurger thanks for the review, made some updates.

I wasn't sure what to do with the docstring for ``replace`` in ``pandas/core/generic.py`` since it's being overwritten in ``series.py`` and ``frame.py``.
can you rebase
I removed the duplication by using ``_shared_docs`` but as a result most of the examples for both the ``Series.replace`` and ``DataFrame.replace`` docstrings now use ``DataFrame``. 
@jorisvandenbossche if you'd have a look. I only glanced briefly :>
thanks!