[IO-1461][IO-1820] Code Documentation + exception refactoring + mypy checking

[Nathanjp91]

Problem

Some undocumented code and dogfooding issues have accrued

Solution

fix the following:

• added documentation as well as examples
• refactored and unified approach to exception handling
• swapped str/repr locations to conform with mypy typechecking

The List[Exception] Paradigm now only exists for things that parse multiple objects. It should raise on other issues like exceptions from underlying http request, but will attempt to parse all objects before failing.

Changelog

Added documentation and dogfooding refactors to futures code

[linear]

IO-1461 Docblock document Query.where

Query.where currently has no doc block documenting it, so IDEs don't hint how it should be used.

Add a docblock with:

• Params
• Return
• Example of use, including MODIFIERS use.

[linear]

IO-1820 Include params and returns in docblocks in darwin.future

Some functions in darwin-py darwin.future module have descriptions but not params.

Expand to include params and returns, e.g.

From

def my_function(a: int, b: str) -> float:
"""
A function that performs an operation on an int and string and returns a float

Paramters
_________
a  int  The int to use
b  str  The string to use

Returns
_______
float

"""
...

[owencjones]

Yep, a lot of it, but good stuff.

[owencjones]

Good catch

[owencjones]

Could've sworn we already had this!

[Nathanjp91]

we do in the old code version, I just copied it across and modified a little

[owencjones]

Maybe need handling of the exceptions here? Consideration point

[Nathanjp91]

good point, I'll add something in. At least a print on failed validations