From 5fb6fb603965fe32ecbb45f408eea4060a979c28 Mon Sep 17 00:00:00 2001
From: Takeshi KOMIYA <i.tkomiya@gmail.com>
Date: Sun, 26 Sep 2021 00:45:18 +0900
Subject: [PATCH] Fix #9651: autodoc_typehints_description_target was confused
 by :returns:

It only checks the existence of `:return:` field.  And it does not check
`:returns:` field.  It causes the absence of return types.
---
 CHANGES                           |  3 +++
 sphinx/ext/autodoc/typehints.py   |  4 ++--
 tests/test_ext_autodoc_configs.py | 12 ++++++++++++
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/CHANGES b/CHANGES
index 49d8dcf8123..0f7a516010f 100644
--- a/CHANGES
+++ b/CHANGES
@@ -24,6 +24,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
diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py
index af4b47bb059..f4b4dd35e57 100644
--- a/sphinx/ext/autodoc/typehints.py
+++ b/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()
diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py
index f6436f541a3..e04cd83b681 100644
--- a/tests/test_ext_autodoc_configs.py
+++ b/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'