diff --git a/CHANGES b/CHANGES index b58c5e34178..56bb70001e6 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index abece421318..dcd857959ee 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/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. diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index 3950b5f640a..e821f5bdeb8 100644 --- a/sphinx/domains/c.py +++ b/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'