Parameters with a default value lose their type information from docstrings

[christianaguilera-foundry]

Consider the following function, which features a parameter that has a default value:

def foobar(name, surname='Smith'):
    """
    This is an example.

    :type name: str
    :type surname: str
    :param name: The name of the user.
    :param surname: The surname of the user.
    """

If sphinx-autodoc-typehints is configured with

typehints_defaults = 'comma'
typehints_use_signature = True

, the mere existence of the default value makes the extension disregard the type information that is present in the docstring:

Ideally, if the parameter provides a default value but not a type hint, the type information in the docstring should be used if it is present:

Important

The issue is reproducible if typehints_defaults is set to 'comma' or 'braces', but not if set to 'braces-after'.

[gaborbernat]

That method doesn't have type annotation 🤔 the ones in the docstring don't count 🤔

[christianaguilera-foundry]

That method doesn't have type annotation 🤔 the ones in the docstring don't count 🤔

Perhaps I'm misunderstanding this comment. I would expect the ones in the docstring to count, just like they do for name (but not for surname).

[christianaguilera-foundry]

Our code base still have lots of Python code written in the Python 2 era, so they don't have type annotations, but do have proper docstrings and occasionally default values, which is the combination that breaks.

[gaborbernat]

Understood, you're very much in the unsupported use case, but if you put in a PR with tests to fix it I can review.