From 93e47600c03740d67eee9c41ca9eebb40fc636dc Mon Sep 17 00:00:00 2001
From: gschwaer <3410079+gschwaer@users.noreply.github.com>
Date: Mon, 29 Nov 2021 19:55:05 +0100
Subject: [PATCH] feat: add new option for autodoc_typehints_description_target
 to include undocumented return values

---
 sphinx/ext/autodoc/__init__.py  |  2 +-
 sphinx/ext/autodoc/typehints.py | 12 ++++++++++--
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index a4d5884e8..b870c6262 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -2831,7 +2831,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_typehints', "signature", True,
                          ENUM("signature", "description", "none", "both"))
     app.add_config_value('autodoc_typehints_description_target', 'all', True,
-                         ENUM('all', 'documented'))
+                         ENUM('all', 'documented', 'returnvalue_and_documented_params'))
     app.add_config_value('autodoc_type_aliases', {}, True)
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)
diff --git a/sphinx/ext/autodoc/typehints.py b/sphinx/ext/autodoc/typehints.py
index f4b4dd35e..fef8ee35e 100644
--- a/sphinx/ext/autodoc/typehints.py
+++ b/sphinx/ext/autodoc/typehints.py
@@ -63,8 +63,15 @@ def merge_typehints(app: Sphinx, domain: str, objtype: str, contentnode: Element
         for field_list in field_lists:
             if app.config.autodoc_typehints_description_target == "all":
                 modify_field_list(field_list, annotations[fullname])
+            elif (app.config.autodoc_typehints_description_target
+                    == "returnvalue_and_documented_params"):
+                augment_descriptions_with_types(
+                    field_list, annotations[fullname], force_rtype=True
+                )
             else:
-                augment_descriptions_with_types(field_list, annotations[fullname])
+                augment_descriptions_with_types(
+                    field_list, annotations[fullname], force_rtype=False
+                )
 
 
 def insert_field_list(node: Element) -> nodes.field_list:
@@ -130,6 +137,7 @@ def modify_field_list(node: nodes.field_list, annotations: Dict[str, str]) -> No
 def augment_descriptions_with_types(
     node: nodes.field_list,
     annotations: Dict[str, str],
+    force_rtype: bool
 ) -> None:
     fields = cast(Iterable[nodes.field], node)
     has_description = set()  # type: Set[str]
@@ -166,7 +174,7 @@ def augment_descriptions_with_types(
 
     # Add 'rtype' if 'return' is present and 'rtype' isn't.
     if 'return' in annotations:
-        if 'return' in has_description and 'return' not in has_type:
+        if 'return' not in has_type and (force_rtype or 'return' in has_description):
             field = nodes.field()
             field += nodes.field_name('', 'rtype')
             field += nodes.field_body('', nodes.paragraph('', annotations['return']))