DOC: Deprecation directive in Docstrings should be placed before the extended summary
- [x] closes #24143
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Two methods still show errors due to their docstrings being generated by the [deprecate](https://github.com/pandas-dev/pandas/blob/v0.23.4/pandas/util/_decorators.py#L10) method in _decorators.py. I am not sure if that is to be changed.