Skip to content

Commit 50dd03d

Browse files
Merge pull request #9693 from jakobandersen/c-info-field
C, info-fields
2 parents 063dcfd + 57fad5c commit 50dd03d

File tree

3 files changed

+63
-12
lines changed

3 files changed

+63
-12
lines changed

CHANGES

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ Features added
1919
* #9639: autodoc: Support asynchronous generator functions
2020
* #9664: autodoc: ``autodoc-process-bases`` supports to inject reST snippet as a
2121
base class
22+
* 9691: C, added new info-field ``retval``
23+
for :rst:dir:`c:function` and :rst:dir:`c:macro`.
2224

2325
Bugs fixed
2426
----------

doc/usage/restructuredtext/domains.rst

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -677,12 +677,55 @@ The C domain (name **c**) is suited for documentation of C API.
677677
Note that you don't have to backslash-escape asterisks in the signature, as
678678
it is not parsed by the reST inliner.
679679

680+
In the description of a function you can use the following info-fields
681+
(see also :ref:`info-field-lists`).
682+
683+
* ``param``, ``parameter``, ``arg``, ``argument``,
684+
Description of a parameter.
685+
* ``type``: Type of a parameter,
686+
written as if passed to the :rst:role:`c:expr` role.
687+
* ``returns``, ``return``: Description of the return value.
688+
* ``rtype``: Return type,
689+
written as if passed to the :rst:role:`c:expr` role.
690+
* ``retval``, ``retvals``: An alternative to ``returns`` for describing
691+
the result of the function.
692+
693+
.. versionadded:: 4.3
694+
The ``retval`` field type.
695+
696+
For example::
697+
698+
.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
699+
700+
:param type: description of the first parameter.
701+
:param nitems: description of the second parameter.
702+
:returns: a result.
703+
:retval NULL: under some conditions.
704+
:retval NULL: under some other conditions as well.
705+
706+
which renders as
707+
708+
.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
709+
710+
..
711+
** for some editors (e.g., vim) to stop bold-highlighting the source
712+
713+
:param type: description of the first parameter.
714+
:param nitems: description of the second parameter.
715+
:returns: a result.
716+
:retval NULL: under some conditions.
717+
:retval NULL: under some other conditions as well.
718+
719+
680720
.. rst:directive:: .. c:macro:: name
681721
.. c:macro:: name(arg list)
682722
683723
Describes a C macro, i.e., a C-language ``#define``, without the replacement
684724
text.
685725
726+
In the description of a macro you can use the same info-fields as for the
727+
:rst:dir:`c:function` directive.
728+
686729
.. versionadded:: 3.0
687730
The function style variant.
688731

sphinx/domains/c.py

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3130,18 +3130,6 @@ class CObject(ObjectDescription[ASTDeclaration]):
31303130
Description of a C language object.
31313131
"""
31323132

3133-
doc_field_types = [
3134-
TypedField('parameter', label=_('Parameters'),
3135-
names=('param', 'parameter', 'arg', 'argument'),
3136-
typerolename='expr', typenames=('type',)),
3137-
GroupedField('retval', label=_('Return values'),
3138-
names=('retvals', 'retval')),
3139-
Field('returnvalue', label=_('Returns'), has_arg=False,
3140-
names=('returns', 'return')),
3141-
Field('returntype', label=_('Return type'), has_arg=False,
3142-
names=('rtype',)),
3143-
]
3144-
31453133
option_spec: OptionSpec = {
31463134
'noindexentry': directives.flag,
31473135
}
@@ -3344,13 +3332,31 @@ def display_object_type(self) -> str:
33443332
return self.objtype
33453333

33463334

3335+
_function_doc_field_types = [
3336+
TypedField('parameter', label=_('Parameters'),
3337+
names=('param', 'parameter', 'arg', 'argument'),
3338+
typerolename='expr', typenames=('type',)),
3339+
GroupedField('retval', label=_('Return values'),
3340+
names=('retvals', 'retval'),
3341+
can_collapse=True),
3342+
Field('returnvalue', label=_('Returns'), has_arg=False,
3343+
names=('returns', 'return')),
3344+
Field('returntype', label=_('Return type'), has_arg=False,
3345+
names=('rtype',)),
3346+
]
3347+
3348+
33473349
class CFunctionObject(CObject):
33483350
object_type = 'function'
33493351

3352+
doc_field_types = _function_doc_field_types.copy()
3353+
33503354

33513355
class CMacroObject(CObject):
33523356
object_type = 'macro'
33533357

3358+
doc_field_types = _function_doc_field_types.copy()
3359+
33543360

33553361
class CStructObject(CObject):
33563362
object_type = 'struct'

0 commit comments

Comments
 (0)