DOC: overall improvement of docstrings
This is a general issue, to have as a starting point for (new) contributors to improve the docstrings (many docstrings have missing parts, and improvements on this front are always welcome).

In general, some attention points for docstrings in pandas. Each docstring should have:

- Clear explanation of the function/method/attribute's purpose and what it does
- Clear explanation of all parameter values
- State the return value and type (xref #17114)
- Some examples
  - Note: examples should be runnable (thus include creation of the example DataFrame/Series, `import pandas as pd` not needed to include) (xref #3439)
- follow more the numpydoc docstring standard (stylistic, see also, all arguments)


There are quite some docstrings that are still lacking on some of these points (in particular examples), and PRs to improve this are always welcome.

**Approach**: pick a function, check the docstring, and if needed make a PR with updates!