Follow up to #244.

• Consider using type annotations instead of including types in arg docstrings, or
• Standardize on arg (`type`): ... instead of arg: a `type` ...
• Remove documentation-related TODOs
• Replace human-readable descriptions of types with valid types, e.g.
  • Optional[type] instead of (`type`, optional)
  • typing.Dict[str, typing.Union[str, bool, float]] instead of A dict with :obj:`str` keys ...

Both sphinx and python type annotations give us more than enough rope to hang ourselves with. Since this is the first public-facing module to include type info for args and return types without a corresponding mypy test, we can use this to establish some conventions for other modules like it.