IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

C, update documentation for info-fields

Browse Source
This commit is contained in:
Jakob Lykke Andersen 2021-10-01 18:38:30 +02:00
parent 65aa3f7f51
commit 57fad5c044
1 changed files with 43 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
doc/usage/restructuredtext/domains.rst
View File

@ -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.