python
python copied to clipboard
mkdocstrings
feature: Improve rendering of function overloads
Is your feature request related to a problem? Please describe.
Originally discussed here: https://github.com/mmacy/openai-python/issues/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: https://github.com/astral-sh/ruff/issues/10071
