DOC: clean-up docstrings of option functions

Some clean-up after my last additions to api.rst to get rid off all warnings:

- some clean up of api.rst itself
- some clean-up of the docstrings of the option functions so they render nicely with sphinx