Wrong “D103: Missing docstring in public function” for overload functions

[raabf]

For example:

from typing import overload

@overload
def func(a: int) -> str:
     ...
@overload
def func(a: str) -> str:
     ...
def func(a):
     """Foo bar documentation."""
     return str(a)

will result in

/home/raabf/Dokumente/overload_test.py:4 in public function `func`:
    D103: Missing docstring in public function
/home/raabf/Dokumente/overload_test.py:7 in public function `func`:
    D103: Missing docstring in public function

Which is wrong since only the last def should have a docstring.

Two things should be done:

First, prevent the error D103 for overload functions. We could make use of the --ignore-decorators='overload', but since it is universally valid, it should be a fixed part of it, and the user should not set it by himself.

Second, since @overload functions should never have docstrings, it would be useful if there is an additional error code in pydocstyle, if someone is setting a docstring for an @overload function.

[Nurdok]

Both ideas sound good to me. PRs welcome.

[rmorshea]

This is a big issue for anyone using type annotations since turning off the error prevents you from ensuring you have documentation coverage. @Nurdok, given this drawback, resolving the issue seems to be of slightly higher priority.

[rmorshea]

I've just noticed that you only have two priority tags so maybe this doesn't rise to the level of "major", but it's worth considering that turning off the error negates the huge benefit of guaranteeing doc coverage.

[thomasgilgenast]

I am also encountering this.

Instead of turning off D102/D103 completely, I think it's possible to add # noqa: D102 or # noqa: D103 to the @overload definitions (but not the real implementation) as a temporary workaround.

[theyuvalraz]

I maybe biting more than I can chew. But I think I will take a stab at this.

If I understand correctly what is needed here is:

1. D103 shouldn't be triggered if the function is decorated with @overload.
2. If a function is decorated with @overload and has a docstring then it should throw a new error code.

[theyuvalraz]

@samj1912
About the second objective: Adding a new error code for "Function decorated with @overload shouldn't contain a docstring"

This does not fit any of the grouping available, Should I create D5XX "shouldn't contain docstring" group?

[sambhav]

I think D4xx may still be a good candidate for this error

[jdtzmn]

Is this also fixed for D102? I'm still getting D102 errors on overloaded functions.

[ShadowLNC]

I'm not seeing D418 errors with the following file:

"""Reproduce D418."""

from typing import overload, Any

@overload
def func(val: str) -> str:
    ...

@overload
def func(val: int) -> int:
    """Return original value."""
    ...

def func(val: Any) -> Any:
    """Return original value."""
    return val

Should I be expecting to see them? pydocstyle --version gives 6.0.0.