From dd53cd2f8c78737aac1ae38a3d4ab8470fb875fe Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Fri, 1 Oct 2021 17:45:10 +0200 Subject: [PATCH 1/4] C, move info-fields from all objects to just function and macro --- sphinx/domains/c.py | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index 3950b5f640a..9acbdd5f821 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,30 @@ 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')), + 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' From 8ed9ebc939617a70961ef8b1e5a4bd90be8db4ce Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Fri, 1 Oct 2021 17:47:08 +0200 Subject: [PATCH 2/4] C, add CHANGES entry for sphinx-doc/sphinx#9691 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) 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 ---------- From 65aa3f7f512914e2d8942c4246366a18b12f7db9 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Fri, 1 Oct 2021 18:38:14 +0200 Subject: [PATCH 3/4] C, fix retvals info-field to be collapsible --- sphinx/domains/c.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index 9acbdd5f821..e821f5bdeb8 100644 --- a/sphinx/domains/c.py +++ b/sphinx/domains/c.py @@ -3337,7 +3337,8 @@ def display_object_type(self) -> str: names=('param', 'parameter', 'arg', 'argument'), typerolename='expr', typenames=('type',)), GroupedField('retval', label=_('Return values'), - names=('retvals', 'retval')), + names=('retvals', 'retval'), + can_collapse=True), Field('returnvalue', label=_('Returns'), has_arg=False, names=('returns', 'return')), Field('returntype', label=_('Return type'), has_arg=False, From 57fad5c04402c508287670a674ee4226f4e8d8fa Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Fri, 1 Oct 2021 18:38:30 +0200 Subject: [PATCH 4/4] C, update documentation for info-fields --- doc/usage/restructuredtext/domains.rst | 43 ++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) 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.