Fix docstring of functions created with the deprecate() function

[datapythonista]

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
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[pep8speaks]

Hello @datapythonista! Thanks for submitting the PR.

• There are no PEP8 issues in the file pandas/tests/util/test_deprecate.py !

• There are no PEP8 issues in the file pandas/util/_decorators.py !

[codecov]

Codecov Report

Merging #24215 into master will decrease coverage by 49.2%.
The diff coverage is 81.81%.

@@             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%)	⬇️

Impacted Files	Coverage Δ
pandas/util/_decorators.py	68.22% <81.81%> (-23.13%)	⬇️
pandas/io/formats/latex.py	0% <0%> (-100%)	⬇️
pandas/core/categorical.py	0% <0%> (-100%)	⬇️
pandas/io/sas/sas_constants.py	0% <0%> (-100%)	⬇️
pandas/tseries/plotting.py	0% <0%> (-100%)	⬇️
pandas/tseries/converter.py	0% <0%> (-100%)	⬇️
pandas/io/formats/html.py	0% <0%> (-98.62%)	⬇️
pandas/core/groupby/categorical.py	0% <0%> (-95.46%)	⬇️
pandas/io/sas/sas7bdat.py	0% <0%> (-91.17%)	⬇️
pandas/io/sas/sas_xport.py	0% <0%> (-90.15%)	⬇️
... and 120 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 91802fb...cc29112. Read the comment docs.

[codecov]

Codecov Report

Merging #24215 into master will increase coverage by <.01%.
The diff coverage is 100%.

@@            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%> (ø)	⬆️
#single	43% <100%> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/util/_decorators.py	91.5% <100%> (+0.16%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 91802fb...7315e63. Read the comment docs.

[jreback]

are these inplace of tests_deprecate_kwarg.py? (this is pretty new)

[datapythonista]

No, they are different. We have an old (I guess) deprecate that is used to deprecate argmax (and argmin) with deprecate('argmax', idmax).

The function was not tested, and I had to modify it, because it was injecting the .. deprecate:: directive in a way that the docstring format was wrong.

[jreback]

lgtm. @jorisvandenbossche or @TomAugspurger

[TomAugspurger]

LGTM, thanks.