Improve docstring structuring for code autocompletion.

[tomchristie]

• The __init__.py module should include a docstring.
• Should class docstrings be on the class itself or on the class __init__ method (or both?).
• Review if we've currently got a docstring on all public API, and review consistency & styling throughout.