diff --git a/CHANGES b/CHANGES index 56bb70001e6..3298acbd247 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index dcd857959ee..99372c1d4b1 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/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 diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py index d53997552cd..7e9d0fd02a8 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'