Report type overloads after doc-string

[Rizhiy]

Is your feature request related to a problem? Please describe.
If a function has type overloads then all overloaded types will be listed first with doc-string at the bottom.
This usually doesn't make much sense, since overload types are usually for better type-checking rather than user-help.

Code example:

from typing import Literal, Union, overload

# fmt: off
@overload
def func(t: Literal["str"]) -> str: ...
@overload
def func(t: Literal["int"]) -> int: ...
# fmt: on


def func(t: str) -> Union[str, int]:
    """
    A description

    :param t: Required type of result
    :return: Some value of requested type
    """
    if t == "str":
        return ""
    if t == "int":
        return 0
    raise ValueError("Unknown type")

Help for the example:

Here with just two overloads it works fine, but if many overloads are used, then only overloads are visible, especially if the function signature itself is long and takes up multiple lines.

Describe the solution you'd like
I would prefer if help was in the following order:
1. Main signature
2. Doc-string
3. All overloaded types

Additional context
There is some uncertainty about what the main signature should be.
In my company we just use Union of all possible types in the main signature, so that should be fine.
Although, I saw that some people leave types in main signature blank, in such cases it might make sense to either try to assemble proper types or leave overloads at the top.

[erictraut]

Thanks for the suggestion. Since this isn't related to core type checking functionality and is instead a language server feature, I'm going to transfer this to the pylance project so it gets the appropriate attention by the pylance team.

[Rizhiy]

Hmm, I don't use pylance, so my example might not apply there.
I guess I need to raise this with coc team as well.

[erictraut]

@Rizhiy, if the pylance team decides to implement this enhancement request or something like it, the behavior will also be reflected in pyright.

[judej]

Moving this issue to discussion as an enhancement request for comments and upvotes.