Merge pull request #9673 from tk0miya/9651_autodoc_typehints_descript…

…ion_target

Fix #9651: autodoc_typehints_description_target was confused by :returns:

CHANGES

@@ -27,6 +27,9 @@ Bugs fixed
   is not 'py'
 * #9644: autodoc: Crashed on getting source info from problematic object
 * #9655: autodoc: mocked object having doc comment is warned unexpectedly
+* #9651: autodoc: return type field is not generated even if
+  :confval:`autodoc_typehints_description_target` is set to "documented" when
+  its info-field-list contains ``:returns:`` field
 * #9630: autosummary: Failed to build summary table if :confval:`primary_domain`
   is not 'py'
 * #9670: html: Fix download file with special characters

sphinx/ext/autodoc/typehints.py

@@ -149,14 +149,14 @@ 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')
 
     # Add 'type' for parameters with a description but no declared type.
     for name in annotations:
-        if name == 'return':
+        if name in ('return', 'returns'):
             continue
         if name in has_description and name not in has_type:
             field = nodes.field()

tests/test_ext_autodoc_configs.py

@@ -844,6 +844,10 @@ def test_autodoc_typehints_description_no_undoc(app):
     (app.srcdir / 'index.rst').write_text(
         '.. autofunction:: target.typehints.incr\n'
         '\n'
+        '.. autofunction:: target.typehints.decr\n'
+        '\n'
+        '   :returns: decremented number\n'
+        '\n'
         '.. autofunction:: target.typehints.tuple_args\n'
         '\n'
         '   :param x: arg\n'
@@ -852,6 +856,14 @@ def test_autodoc_typehints_description_no_undoc(app):
     app.build()
     context = (app.outdir / 'index.txt').read_text()
     assert ('target.typehints.incr(a, b=1)\n'
+            '\n'
+            'target.typehints.decr(a, b=1)\n'
+            '\n'
+            '   Returns:\n'
+            '      decremented number\n'
+            '\n'
+            '   Return type:\n'
+            '      int\n'
             '\n'
             'target.typehints.tuple_args(x)\n'
             '\n'