type-hintingpep8docstringnumpydoc

numpydoc: Can I omit the type declaration in the docstring when I use type hints?


When using type hints in the function signature, do I need to specify the parameter types in the docstring, too, if I were to comply with numpydoc style?

def add(a: float, b: int) -> float:
    """

    Parameters
    ----------
    a
        Fist number.
    b : int
        Second number.

    Returns
    -------
    float
        Result of a + b

    """
    return a + b

Is the defintion for a in the parameters section sufficient?


Solution

  • At present I think the answer is no if you want to use the numpydoc python package directly. There is an open ticket: https://github.com/numpy/numpydoc/issues/196

    I expect any changes will also appear in numpydoc documentation.

    However: rendering docstrings written in numpydoc-like type-hinted style might work via other packages. Here's what I've found (partly via that numpydoc issue):