Merge pull request #9693 from jakobandersen/c-info-field

C, info-fields

CHANGES

@@ -19,6 +19,8 @@ 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``
+  for :rst:dir:`c:function` and :rst:dir:`c:macro`.
 
 Bugs fixed
 ----------

doc/usage/restructuredtext/domains.rst

@@ -677,12 +677,55 @@ 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
+   (see also :ref:`info-field-lists`).
+
+   * ``param``, ``parameter``, ``arg``, ``argument``,
+     Description of a parameter.
+   * ``type``: Type of a parameter,
+     written as if passed to the :rst:role:`c:expr` role.
+   * ``returns``, ``return``: Description of the return value.
+   * ``rtype``: Return type,
+     written as if passed to the :rst:role:`c:expr` role.
+   * ``retval``, ``retvals``: An alternative to ``returns`` for describing
+     the result of the function.
+
+   .. versionadded:: 4.3
+      The ``retval`` field type.
+
+   For example::
+
+      .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+         :param type: description of the first parameter.
+         :param nitems: description of the second parameter.
+         :returns: a result.
+         :retval NULL: under some conditions.
+         :retval NULL: under some other conditions as well.
+
+   which renders as
+
+   .. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+      ..
+         ** for some editors (e.g., vim) to stop bold-highlighting the source
+
+      :param type: description of the first parameter.
+      :param nitems: description of the second parameter.
+      :returns: a result.
+      :retval NULL: under some conditions.
+      :retval NULL: under some other conditions as well.
+
+
 .. rst:directive:: .. c:macro:: name
                    .. c:macro:: name(arg list)
 
    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
+   :rst:dir:`c:function` directive.
+
    .. versionadded:: 3.0
       The function style variant.
 

sphinx/domains/c.py

@@ -3130,18 +3130,6 @@ class CObject(ObjectDescription[ASTDeclaration]):
     Description of a C language object.
     """
 
-    doc_field_types = [
-        TypedField('parameter', label=_('Parameters'),
-                   names=('param', 'parameter', 'arg', 'argument'),
-                   typerolename='expr', typenames=('type',)),
-        GroupedField('retval', label=_('Return values'),
-                     names=('retvals', 'retval')),
-        Field('returnvalue', label=_('Returns'), has_arg=False,
-              names=('returns', 'return')),
-        Field('returntype', label=_('Return type'), has_arg=False,
-              names=('rtype',)),
-    ]
-
     option_spec: OptionSpec = {
         'noindexentry': directives.flag,
     }
@@ -3344,13 +3332,31 @@ def display_object_type(self) -> str:
         return self.objtype
 
 
+_function_doc_field_types = [
+    TypedField('parameter', label=_('Parameters'),
+               names=('param', 'parameter', 'arg', 'argument'),
+               typerolename='expr', typenames=('type',)),
+    GroupedField('retval', label=_('Return values'),
+                 names=('retvals', 'retval'),
+                 can_collapse=True),
+    Field('returnvalue', label=_('Returns'), has_arg=False,
+          names=('returns', 'return')),
+    Field('returntype', label=_('Return type'), has_arg=False,
+          names=('rtype',)),
+]
+
+
 class CFunctionObject(CObject):
     object_type = 'function'
 
+    doc_field_types = _function_doc_field_types.copy()
+
 
 class CMacroObject(CObject):
     object_type = 'macro'
 
+    doc_field_types = _function_doc_field_types.copy()
+
 
 class CStructObject(CObject):
     object_type = 'struct'