Better docstrings with parameter and return information

[tga]

Many functions need better parameter documentation in their docstring because without it, it is difficult to understand what's going on.

Bonus points while doing this: use Sphinx style (:param foo: Description).

1) it provides a standard way of writing docstrings,

2) is already in use in docs, and

3) it will also help with IDE support.