From 20c9a245c21b7466c35b581d1f825002f3840f31 Mon Sep 17 00:00:00 2001
From: Casey Brooks <casey.brooks@agyn.io>
Date: Fri, 26 Dec 2025 21:01:47 +0000
Subject: [PATCH] fix(autodoc): inject return type for google docstrings

---
 sphinx/ext/autodoc/typehints.py               |  6 ++---
 .../target/google_style_returns.py            | 11 +++++++++
 tests/test_ext_autodoc_configs.py             | 24 +++++++++++++++++++
 3 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 tests/roots/test-ext-autodoc/target/google_style_returns.py

diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py
index af4b47bb059..d90d36452a7 100644
--- a/sphinx/ext/autodoc/typehints.py
+++ b/sphinx/ext/autodoc/typehints.py
@@ -132,8 +132,8 @@ def augment_descriptions_with_types(
     annotations: Dict[str, str],
 ) -> None:
     fields = cast(Iterable[nodes.field], node)
-    has_description = set()  # type: Set[str]
-    has_type = set()  # type: Set[str]
+    has_description: Set[str] = set()
+    has_type: Set[str] = set()
     for field in fields:
         field_name = field[0].astext()
         parts = re.split(' +', field_name)
@@ -149,7 +149,7 @@ def augment_descriptions_with_types(
         elif parts[0] == 'type':
             name = ' '.join(parts[1:])
             has_type.add(name)
-        elif parts[0] == 'return':
+        elif parts[0] in ('return', 'returns'):
             has_description.add('return')
         elif parts[0] == 'rtype':
             has_type.add('return')
diff --git a/tests/roots/test-ext-autodoc/target/google_style_returns.py b/tests/roots/test-ext-autodoc/target/google_style_returns.py
new file mode 100644
index 00000000000..f63face2d2a
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/google_style_returns.py
@@ -0,0 +1,11 @@
+"""Test module for Google-style return docstrings."""
+
+
+def documented_return() -> str:
+    """Return a greeting.
+
+    Returns:
+        Greeting message.
+    """
+
+    return "hello"
diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py
index f6436f541a3..6d0d16d12e0 100644
--- a/tests/test_ext_autodoc_configs.py
+++ b/tests/test_ext_autodoc_configs.py
@@ -866,6 +866,30 @@ def test_autodoc_typehints_description_no_undoc(app):
             in context)
 
 
+@pytest.mark.sphinx(
+    'text',
+    testroot='ext-autodoc',
+    confoverrides={
+        'extensions': ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'],
+        'napoleon_google_docstring': True,
+        'autodoc_typehints': 'description',
+        'autodoc_typehints_description_target': 'documented',
+    },
+)
+def test_autodoc_typehints_description_google_returns(app):
+    (app.srcdir / 'index.rst').write_text(
+        '.. autofunction:: target.google_style_returns.documented_return\n'
+    )
+    app.build()
+    context = (app.outdir / 'index.txt').read_text()
+    assert ('   Returns:\n'
+            '      Greeting message.\n'
+            in context)
+    assert ('   Return type:\n'
+            '      str\n'
+            in context)
+
+
 @pytest.mark.sphinx('text', testroot='ext-autodoc',
                     confoverrides={'autodoc_typehints': "description"})
 def test_autodoc_typehints_description_with_documented_init(app):