Merge pull request sphinx-doc#9694 from jakobandersen/cpp-info-fields

C++, add retval info field

Author: jakobandersen

CHANGES

@@ -19,8 +19,9 @@ Features added
 * #9639: autodoc: Support asynchronous generator functions
 * #9664: autodoc: ``autodoc-process-bases`` supports to inject reST snippet as a
   base class
-* 9691: C, added new info-field ``retval``
+* #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
 ----------

doc/usage/restructuredtext/domains.rst

@@ -677,7 +677,7 @@ The C domain (name **c**) is suited for documentation of C API.
    Note that you don't have to backslash-escape asterisks in the signature, as
    it is not parsed by the reST inliner.
 
-   In the description of a function you can use the following info-fields
+   In the description of a function you can use the following info fields
    (see also :ref:`info-field-lists`).
 
    * ``param``, ``parameter``, ``arg``, ``argument``,
@@ -723,7 +723,7 @@ The C domain (name **c**) is suited for documentation of C API.
    Describes a C macro, i.e., a C-language ``#define``, without the replacement
    text.
 
-   In the description of a macro you can use the same info-fields as for the
+   In the description of a macro you can use the same info fields as for the
    :rst:dir:`c:function` directive.
 
    .. versionadded:: 3.0
@@ -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

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'