feature: Improve rendering of function overloads

[pawamoy]

Is your feature request related to a problem? Please describe.

Originally discussed here: mmacy/openai-python#7

It can be useful to have docstrings in overloads as well as in the implementation. For example VSCode understands those and will show/autocomplete the right parameters based on what you already typed.

mkdocstrings-python currently only renders signatures of overloads, and expects a docstring to only appear in the implementation. Maybe we can do better?

Describe the solution you'd like

Not exactly sure. Copying the comment from the linked discussion:

from typing import overload


@overload
def f(a: int, x: bool) -> str:
    """Specific summary.

    Specific body.
    
    Args:
        a: Specific description.
        x: Common description.
    """
    ...


@overload
def f(b: str, x: bool) -> str:
    """Specific summary.

    Specific body.
    
    Args:
        b: Specific description.
        x: Common description.
    """
    ...


def f(
    x: bool,
    a: int | None = None,
    b: str | None = None,
) -> str:
    """Generic summary.

    Generic body.

    Args:
        a: Generic description.
        b: Generic description.
        x: Common description.
    """
    return ...

A few things to take into account for mkdocstrings:

• we can have only one entry in the object inventory for function f
• we can have only one entry in the object inventory for each parameter (a, b, c, d, x)
• but maybe we can suffix links and ids such that parameters from overload 1 link to descriptions in overload 1, etc.

Describe alternatives you've considered

/

Additional context

Discussion in Ruff: astral-sh/ruff#10071