Parameter descriptions and typing

[trickeydan]

e.g

def format_unit(value, unit):
    """
    Formats the given value as a human readable string using the given units.

    :param float|int value: a numeric value
    :param str unit: the unit for the value (kg, m, etc.)
    :rtype: str
    """
    return '{} {}'.format(value, unit)

We should consider this: https://pypi.org/project/sphinx-autodoc-typehints/

[sedders123]

I'm adding this to the Pre-1.0.0 milestone. My reasoning is that if you call help() providing a class, function or property Python will display the relevant docstring. This could help both competitors and implementors to discover more of the API without having to refer to the docs.

Happy to discuss this addition if anyone disagrees.

[trickeydan]

Darglint is likely to be very helpful with this.

I've been unable to configure it exactly how we want, so some upstream contributions may be needed.