overload-with-docstring (D418)#
Derived from the pydocstyle linter.
What it does#
Checks for @overload function definitions that contain a docstring.
Why is this bad?#
The @overload decorator is used to define multiple compatible signatures
for a given function, to support type-checking. A series of @overload
definitions should be followed by a single non-decorated definition that
contains the implementation of the function.
@overload function definitions should not contain a docstring; instead,
the docstring should be placed on the non-decorated definition that contains
the implementation.
Example#
from typing import overload
@overload
def factorial(n: int) -> int:
"""Return the factorial of n."""
@overload
def factorial(n: float) -> float:
"""Return the factorial of n."""
def factorial(n):
"""Return the factorial of n."""
factorial.__doc__ # "Return the factorial of n."
Use instead:
from typing import overload
@overload
def factorial(n: int) -> int:
...
@overload
def factorial(n: float) -> float:
...
def factorial(n):
"""Return the factorial of n."""
factorial.__doc__ # "Return the factorial of n."