Preserve type information from docstrings if no type annotation is present and parameter has default value.

Fixes #574.

Author: christianaguilera-foundry

src/sphinx_autodoc_typehints/__init__.py

@@ -808,45 +808,81 @@ def _inject_signature(
     lines: list[str],
 ) -> None:
     for arg_name in signature.parameters:
-        annotation = type_hints.get(arg_name)
-
-        default = signature.parameters[arg_name].default
-
-        if arg_name.endswith("_"):
-            arg_name = f"{arg_name[:-1]}\\_"  # noqa: PLW2901
-
-        insert_index = None
-        for at, line in enumerate(lines):
-            if _line_is_param_line_for_arg(line, arg_name):
-                # Get the arg_name from the doc to match up for type in case it has a star prefix.
-                # Line is in the correct format so this is guaranteed to return tuple[str, str].
-                func = _get_sphinx_line_keyword_and_argument
-                _, arg_name = func(line)  # type: ignore[assignment, misc] # noqa: PLW2901
-                insert_index = at
-                break
-
-        if annotation is not None and insert_index is None and app.config.always_document_param_types:
-            lines.append(f":param {arg_name}:")
-            insert_index = len(lines)
-
-        if insert_index is not None:
-            if annotation is None:
-                type_annotation = f":type {arg_name}: "
-            else:
-                short_literals = app.config.python_display_short_literal_types
-                formatted_annotation = add_type_css_class(
-                    format_annotation(annotation, app.config, short_literals=short_literals)
-                )
-                type_annotation = f":type {arg_name}: {formatted_annotation}"
+        _inject_arg_signature(type_hints, signature, app, lines, arg_name)
+
+
+def _inject_arg_signature(
+    type_hints: dict[str, Any],
+    signature: inspect.Signature,
+    app: Sphinx,
+    lines: list[str],
+    arg_name: str,
+) -> None:
+    annotation = type_hints.get(arg_name)
+
+    default = signature.parameters[arg_name].default
+
+    if arg_name.endswith("_"):
+        arg_name = f"{arg_name[:-1]}\\_"
+
+    insert_index = None
+    for at, line in enumerate(lines):
+        if _line_is_param_line_for_arg(line, arg_name):
+            # Get the arg_name from the doc to match up for type in case it has a star prefix.
+            # Line is in the correct format so this is guaranteed to return tuple[str, str].
+            _, arg_name = _get_sphinx_line_keyword_and_argument(line)  # type: ignore[assignment, misc]
+            insert_index = at
+            break
+
+    if annotation is not None and insert_index is None and app.config.always_document_param_types:
+        lines.append(f":param {arg_name}:")
+        insert_index = len(lines)
 
-            if app.config.typehints_defaults:
-                formatted_default = format_default(app, default, annotation is not None)
-                if formatted_default:
-                    type_annotation = _append_default(app, lines, insert_index, type_annotation, formatted_default)
+    if insert_index is not None:
+        update_only = False
 
+        if annotation is None:
+            type_annotation, insert_index, update_only = _find_preexisting_type_annotation(
+                lines,
+                arg_name,
+                insert_index,
+            )
+
+        else:
+            short_literals = app.config.python_display_short_literal_types
+            formatted_annotation = add_type_css_class(
+                format_annotation(annotation, app.config, short_literals=short_literals)
+            )
+            type_annotation = f":type {arg_name}: {formatted_annotation}"
+
+        if app.config.typehints_defaults:
+            formatted_default = format_default(app, default, annotation is not None)
+            if formatted_default:
+                type_annotation = _append_default(app, lines, insert_index, type_annotation, formatted_default)
+
+        if update_only:
+            lines[insert_index] = type_annotation
+        else:
             lines.insert(insert_index, type_annotation)
 
 
+def _find_preexisting_type_annotation(
+    lines: list[str],
+    arg_name: str,
+    insert_index: int,
+) -> tuple[str, int, bool]:
+    """
+    Find a type entry in the input docstring that matches the given arg name.
+
+    If not found, a placeholder type entry that can be inserted at the given index is returned.
+    """
+    type_annotation = f":type {arg_name}: "
+    for at, line in enumerate(lines):
+        if line.startswith(type_annotation):
+            return line, at, True
+    return type_annotation, insert_index, False
+
+
 def _append_default(
     app: Sphinx, lines: list[str], insert_index: int, type_annotation: str, formatted_default: str
 ) -> str:
@@ -864,7 +900,8 @@ def _append_default(
         lines[append_index] += formatted_default
 
     else:  # add to last param doc line
-        type_annotation += formatted_default
+        separator = "" if type_annotation.endswith(" ") else ", "
+        type_annotation = f"{type_annotation}{separator}{formatted_default}"
 
     return type_annotation
 

tests/roots/test-dummy/dummy_module_without_complete_typehints.py

@@ -35,3 +35,14 @@ def function_with_defaults_and_some_typehints(x: int = 0, y=None) -> str:  # noq
     :param x: foo
     :param y: bar
     """
+
+
+def function_with_defaults_and_type_information_in_docstring(x, y=0) -> str:  # noqa: ANN001
+    """
+    Function docstring.
+
+    :type x: int
+    :type y: int
+    :param x: foo
+    :param y: bar
+    """

tests/test_sphinx_autodoc_typehints.py

@@ -1074,6 +1074,18 @@ def test_default_annotation_without_typehints(app: SphinxTestApp, status: String
 
        Return type:
           "str"
+
+    dummy_module_without_complete_typehints.function_with_defaults_and_type_information_in_docstring(x, y=0)
+
+       Function docstring.
+
+       Parameters:
+          * **x** ("int") -- foo
+
+          * **y** ("int", default: "0") -- bar
+
+       Return type:
+          "str"
     """
     assert text_contents == dedent(expected_contents)