Fix docstrings
- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `black pandas`
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

This fixes some docstring formatting issues: e.g. some deprecated directives do not appear in current docs because the two colons are missing `.. deprecated 0.25.0`.
odd that the doc string checks don’t catch this
don’t mind fixing these - but should put in place in validate_docstrings.py

@datapythonista  @datapythonista 
> It feels like sphinx should be raising warnings for those, but I guess both sphinx and our script consider those as just part of a paragraph.

2 dots followed by text (and no 2 colons) are valid reST _comments_, thus ignored by the parser: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#comments
 Thanks @albertvillanova, that's good to know. I think then we should make sure in `scripts/validate_docstrings.py` that we don't find "comments" that start with one of the keywords that we know won't be comments (deprecated, versionadded,...).

If you don't mind creating an issue for that, and referencing this PR in it, so we can see where it came from, that would be great.

And thanks for the PR!