Fix docstring of functions created with the deprecate() function
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
