autodoc_typehints="description" doesn't use __init__ type hints

[godlygeek]

Describe the bug
Type hints attached to the __init__ method are not used when autodoc_typehints="description", but are used when autodoc_typehints="signature".

To Reproduce
Create module.py with these contents:

class Person(object):
    """Represent a person.

    Args:
        name: The person's name
    """
    def __init__(self, name: str) -> None:
        self.name = name

    def greet(self, salutation: str) -> None:
        """Print a custom greeting to this person.

        Args:
            salutation: The words to begin the greeting.
        """
        print(salutation + ", " + self.name + "!")

Create index.rst with these contents:

.. automodule:: module
   :members:

Generate documentation into an html directory:

python3.8 -msphinx -aE -C -D 'extensions=sphinx.ext.autodoc,sphinx.ext.napoleon' -D autodoc_typehints=description . html

Expected behavior
The name parameter of the Person constructor should have a (str) type annotation, like the salutation parameter of greet does. When autodoc_typehints="signature", the signature does include the : str type annotation. Adding -D autoclass_content=both causes the type hint to be used, but:

1. I believe the type hint should be used even for autoclass_content="class" like it is if autodoc_typehints="signature", and
2. Using autoclass_content=both causes a Return type: None annotation to be added, which is not helpful for a constructor and which doesn't match the behavior of autodoc_typehints="signature" (there's no -> None in that case).

Environment info

• OS: Linux
• Python version: 3.8.5
• Sphinx version: 3.2.1
• Sphinx extensions: sphinx.ext.autodoc and sphinx.ext.napoleon

Additional context
This appears to be intentional behavior as it was the fix for #7329, but I believe it is incorrect because it is inconsistent with how signature type hints are handled.

[godlygeek]

The bug reported in #7329 was that, when autodoc_typehints="description", autoclass_content="class", and __init__ is documented separately from the class because special-members includes __init__, the constructor parameters would be duplicated in both the class documentation and the __init__ method documentation, and the documentation for the parameters attached to the class docstring would be missing the parameter description and have only the type. This happened because autodoc_typehints="description" will add parameters with annotations to the documentation even if they weren't already present in the docstring.

The fix that was applied makes it so that autodoc_typehints="description" will never modify a class docstring if autoclass_content="class".

This means that autodoc_typehints="description" is broken when autoclass_content="class" (the default) and arguments are documented in the class docstring (as both the Google and Numpy style docstrings do).

I suggest instead changing sphinx.ext.autodoc.typehints.modify_field_list to never add a :param:, only add a :type: for parameters with a pre-existing :param:, and to likewise only add an :rtype: if there was already a :return:. This would fix several issues:

• The bug noted in autodoc_typehints='description' does not combine well with autoclass_content='class' #7329 will be fixed: only the __init__ docstring has a :param: in it, so the class description will be left unchanged by autodoc_typehints
• It will now be possible to have parameters that have type hints, but that are not shown in the documentation. I've been surprised in the past when an entry got added to my documentation for kwargs with only a declared type and no description; this would fix that.
• A function that returns None will no longer have Return type: None added unconditionally. While this is not incorrect, it is distracting, adds little value, and takes up valuable space.

The fix for #7329 fixed one special case of autodoc_typehints="description" documenting only a parameter's type without any description. This proposal would fix the general case by putting the user in control of which parameters are documented and reenabling automatic :type: documentation for constructor parameters.

[godlygeek]

Addressed by #8539, which will ship as part of 4.0