doc(API): Cleaned up API docstrings

Brought docstrings up to date, added type annotations, and clarified some
confusing text.