C++, add retval info field to cpp:function

3 files changed, 30 insertions, 14 deletions

diff --git a/CHANGES b/CHANGES
index 56bb70001..3eac7c76f 100644
--- a/CHANGES
+++ b/CHANGES
@@ -21,6 +21,7 @@ Features added
   base class
 * 9691: C, added new info-field ``retval``
   for :rst:dir:`c:function` and :rst:dir:`c:macro`.
+* C++, added new info-field ``retval`` for :rst:dir:`cpp:function`.
 
 Bugs fixed
 ----------
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index dcd857959..aed756e97 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/doc/usage/restructuredtext/domains.rst
@@ -1496,14 +1496,23 @@ The ``cpp:namespace-pop`` directive undoes the most recent
 Info field lists
 ~~~~~~~~~~~~~~~~~
 
-The C++ directives support the following info fields (see also
-:ref:`info-field-lists`):
+All the C++ directives for declaring entities support the following
+info fields (see also :ref:`info-field-lists`):
 
-* `param`, `parameter`, `arg`, `argument`: Description of a parameter.
-* `tparam`: Description of a template parameter.
-* `returns`, `return`: Description of a return value.
+* ``tparam``: Description of a template parameter.
+
+The :rst:dir:`cpp:function` directive additionally supports the
+following fields:
+
+* ``param``, ``parameter``, ``arg``, ``argument``: Description of a parameter.
+* ``returns``, ``return``: Description of a return value.
+* ``retval``, ``retvals``: An alternative to ``returns`` for describing
+  the result of the function.
 * `throws`, `throw`, `exception`: Description of a possibly thrown exception.
 
+.. versionadded:: 4.3
+   The ``retval`` field type.
+
 .. _cpp-roles:
 
 Cross-referencing
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index d53997552..7e9d0fd02 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -6934,18 +6934,10 @@ def _make_phony_error_name() -> ASTNestedName:
 class CPPObject(ObjectDescription[ASTDeclaration]):
     """Description of a C++ language object."""
 
-    doc_field_types = [
-        GroupedField('parameter', label=_('Parameters'),
-                     names=('param', 'parameter', 'arg', 'argument'),
-                     can_collapse=True),
+    doc_field_types: List[Field] = [
         GroupedField('template parameter', label=_('Template Parameters'),
                      names=('tparam', 'template parameter'),
                      can_collapse=True),
-        GroupedField('exceptions', label=_('Throws'), rolename='expr',
-                     names=('throws', 'throw', 'exception'),
-                     can_collapse=True),
-        Field('returnvalue', label=_('Returns'), has_arg=False,
-              names=('returns', 'return')),
     ]
 
     option_spec: OptionSpec = {
@@ -7181,6 +7173,20 @@ class CPPMemberObject(CPPObject):
 class CPPFunctionObject(CPPObject):
     object_type = 'function'
 
+    doc_field_types = CPPObject.doc_field_types + [
+        GroupedField('parameter', label=_('Parameters'),
+                     names=('param', 'parameter', 'arg', 'argument'),
+                     can_collapse=True),
+        GroupedField('exceptions', label=_('Throws'), rolename='expr',
+                     names=('throws', 'throw', 'exception'),
+                     can_collapse=True),
+        GroupedField('retval', label=_('Return values'),
+                     names=('retvals', 'retval'),
+                     can_collapse=True),
+        Field('returnvalue', label=_('Returns'), has_arg=False,
+              names=('returns', 'return')),
+    ]
+
 
 class CPPClassObject(CPPObject):
     object_type = 'class'