Decide on final docstring format

[tovrstra]

We can see examples of google and numpy docstrings here

http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

[matt-chan]

So both the numpy and google docstrings have legacy formats where type are specified in the docstring and also modern ones where the type is in a 3.5-ish typehint.

I think the numpy style looks better. Also there's a smaller number of indents, which should be less trouble for programming.

[tovrstra]

Sounds good. I'm just adding reference for those who are new to this.

• Type hinting: https://docs.python.org/3/library/typing.html
• Pragmatic introduction: https://blog.jetbrains.com/pycharm/2015/11/python-3-5-type-hinting-in-pycharm-5/
• A talk of Guido on the whyl: https://www.youtube.com/watch?v=2wDvzy6Hgxg

@matt-chan can you add links to a numpydoc spec with the type hinting?