Fix docstring of functions created with the deprecate() function
State: closed

Functions created with `deprecate` function in `pandas.util._decorators` are causing us some problems, for example in #24188, as the docstring is created automatically, and the `.. deprecate::` directive was added at the start. This PR fixes the docstring of the functions created with `deprecate` and adds tests to the function, as they were non-existent.

- [ ] closes #xxxx
- [X] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs

Comments:
Hello @datapythonista! Thanks for submitting the PR.

 - There are no PEP8 issues in the file [`pandas/tests/util/test_deprecate.py`](https://github.com/datapythonista/pandas/blob/24c20eccafebe9a535991521242f39a6e1389db5/pandas/tests/util/test_deprecate.py) !

 - There are no PEP8 issues in the file [`pandas/util/_decorators.py`](https://github.com/datapythonista/pandas/blob/24c20eccafebe9a535991521242f39a6e1389db5/pandas/util/_decorators.py) !


# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24215?src=pr&el=h1) Report
> Merging [#24215](https://codecov.io/gh/pandas-dev/pandas/pull/24215?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/91802fb0accde031c3b6aca040a8b533a193fef6?src=pr&el=desc) will **decrease** coverage by `49.2%`.
> The diff coverage is `81.81%`.

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

```diff
@@             Coverage Diff             @@
##           master   #24215       +/-   ##
===========================================
- Coverage   92.21%      43%   -49.21%     
===========================================
  Files         162      162               
  Lines       51763    51766        +3     
===========================================
- Hits        47733    22262    -25471     
- Misses       4030    29504    +25474
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `?` | |
| #single | `43% <81.81%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24215?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/util/\_decorators.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX2RlY29yYXRvcnMucHk=) | `68.22% <81.81%> (-23.13%)` | :arrow_down: |
| [pandas/io/formats/latex.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvbGF0ZXgucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/core/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvY2F0ZWdvcmljYWwucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/sas/sas\_constants.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNfY29uc3RhbnRzLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/plotting.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvcGxvdHRpbmcucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvY29udmVydGVyLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/formats/html.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvaHRtbC5weQ==) | `0% <0%> (-98.62%)` | :arrow_down: |
| [pandas/core/groupby/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9jYXRlZ29yaWNhbC5weQ==) | `0% <0%> (-95.46%)` | :arrow_down: |
| [pandas/io/sas/sas7bdat.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXM3YmRhdC5weQ==) | `0% <0%> (-91.17%)` | :arrow_down: |
| [pandas/io/sas/sas\_xport.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNfeHBvcnQucHk=) | `0% <0%> (-90.15%)` | :arrow_down: |
| ... and [120 more](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24215?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/24215?src=pr&el=footer). Last update [91802fb...cc29112](https://codecov.io/gh/pandas-dev/pandas/pull/24215?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/24215?src=pr&el=h1) Report
> Merging [#24215](https://codecov.io/gh/pandas-dev/pandas/pull/24215?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/91802fb0accde031c3b6aca040a8b533a193fef6?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/24215/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/24215?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #24215      +/-   ##
==========================================
+ Coverage   92.21%   92.21%   +<.01%     
==========================================
  Files         162      162              
  Lines       51763    51765       +2     
==========================================
+ Hits        47733    47735       +2     
  Misses       4030     4030
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.61% <100%> (ø)` | :arrow_up: |
| #single | `43% <100%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24215?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/util/\_decorators.py](https://codecov.io/gh/pandas-dev/pandas/pull/24215/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX2RlY29yYXRvcnMucHk=) | `91.5% <100%> (+0.16%)` | :arrow_up: |

------

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

lgtm. @jorisvandenbossche or @TomAugspurger 
LGTM, thanks.