[Python-checkins] bpo-43959: clarify the documentation of the PyContextVar C-API (GH-25671) (GH-25690)

[scoder]

https://github.com/python/cpython/commit/ff7266efd0ef6b42dad30c9c0d210f843cc44f39
commit: ff7266efd0ef6b42dad30c9c0d210f843cc44f39
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: scoder <stefan_ml at behnel.de>
date: 2021-04-28T17:11:53+02:00
summary:

bpo-43959: clarify the documentation of the PyContextVar C-API (GH-25671) (GH-25690)

(cherry picked from commit 4c49be766897968e509c41397e0e624c25b1675d)

files:
A Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst
M Doc/c-api/contextvars.rst

diff --git a/Doc/c-api/contextvars.rst b/Doc/c-api/contextvars.rst
index 38256a3b0f2a06..314c8b7847e898 100644
--- a/Doc/c-api/contextvars.rst
+++ b/Doc/c-api/contextvars.rst
@@ -112,9 +112,9 @@ Context variable functions:
 .. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def)
 
    Create a new ``ContextVar`` object.  The *name* parameter is used
-   for introspection and debug purposes.  The *def* parameter may optionally
-   specify the default value for the context variable.  If an error has
-   occurred, this function returns ``NULL``.
+   for introspection and debug purposes.  The *def* parameter specifies
+   a default value for the context variable, or ``NULL`` for no default.
+   If an error has occurred, this function returns ``NULL``.
 
 .. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value)
 
@@ -129,13 +129,12 @@ Context variable functions:
    - the default value of *var*, if not ``NULL``;
    - ``NULL``
 
-   If the value was found, the function will create a new reference to it.
+   Except for ``NULL``, the function returns a new reference.
 
 .. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value)
 
-   Set the value of *var* to *value* in the current context.  Returns a
-   pointer to a :c:type:`PyObject` object, or ``NULL`` if an error
-   has occurred.
+   Set the value of *var* to *value* in the current context.  Returns
+   a new token object for this change, or ``NULL`` if an error has occurred.
 
 .. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token)
 
diff --git a/Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst b/Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst
new file mode 100644
index 00000000000000..ba23ffd577b3d4
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst
@@ -0,0 +1 @@
+The documentation on the PyContextVar C-API was clarified.