Add docstrings to public methods from context.c (GH-8531)

1 files changed, 36 insertions, 9 deletions

diff --git a/Python/clinic/context.c.h b/Python/clinic/context.c.h
index dcf4c214e1..683b9d7902 100644
--- a/Python/clinic/context.c.h
+++ b/Python/clinic/context.c.h
@@ -5,7 +5,11 @@ preserve
 PyDoc_STRVAR(_contextvars_Context_get__doc__,
 "get($self, key, default=None, /)\n"
 "--\n"
-"\n");
+"\n"
+"Return the value for `key` if `key` has the value in the context object.\n"
+"\n"
+"If `key` does not exist, return `default`. If `default` is not given,\n"
+"return None.");
 
 #define _CONTEXTVARS_CONTEXT_GET_METHODDEF    \
     {"get", (PyCFunction)_contextvars_Context_get, METH_FASTCALL, _contextvars_Context_get__doc__},
@@ -35,7 +39,10 @@ exit:
 PyDoc_STRVAR(_contextvars_Context_items__doc__,
 "items($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Return all variables and their values in the context object.\n"
+"\n"
+"The result is returned as a list of 2-tuples (variable, value).");
 
 #define _CONTEXTVARS_CONTEXT_ITEMS_METHODDEF    \
     {"items", (PyCFunction)_contextvars_Context_items, METH_NOARGS, _contextvars_Context_items__doc__},
@@ -52,7 +59,8 @@ _contextvars_Context_items(PyContext *self, PyObject *Py_UNUSED(ignored))
 PyDoc_STRVAR(_contextvars_Context_keys__doc__,
 "keys($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Return a list of all variables in the context object.");
 
 #define _CONTEXTVARS_CONTEXT_KEYS_METHODDEF    \
     {"keys", (PyCFunction)_contextvars_Context_keys, METH_NOARGS, _contextvars_Context_keys__doc__},
@@ -69,7 +77,8 @@ _contextvars_Context_keys(PyContext *self, PyObject *Py_UNUSED(ignored))
 PyDoc_STRVAR(_contextvars_Context_values__doc__,
 "values($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Return a list of all variables’ values in the context object.");
 
 #define _CONTEXTVARS_CONTEXT_VALUES_METHODDEF    \
     {"values", (PyCFunction)_contextvars_Context_values, METH_NOARGS, _contextvars_Context_values__doc__},
@@ -86,7 +95,8 @@ _contextvars_Context_values(PyContext *self, PyObject *Py_UNUSED(ignored))
 PyDoc_STRVAR(_contextvars_Context_copy__doc__,
 "copy($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Return a shallow copy of the context object.");
 
 #define _CONTEXTVARS_CONTEXT_COPY_METHODDEF    \
     {"copy", (PyCFunction)_contextvars_Context_copy, METH_NOARGS, _contextvars_Context_copy__doc__},
@@ -103,7 +113,14 @@ _contextvars_Context_copy(PyContext *self, PyObject *Py_UNUSED(ignored))
 PyDoc_STRVAR(_contextvars_ContextVar_get__doc__,
 "get($self, default=None, /)\n"
 "--\n"
-"\n");
+"\n"
+"Return a value for the context variable for the current context.\n"
+"\n"
+"If there is no value for the variable in the current context, the method will:\n"
+" * return the value of the default argument of the method, if provided; or\n"
+" * return the default value for the context variable, if it was created\n"
+"   with one; or\n"
+" * raise a LookupError.");
 
 #define _CONTEXTVARS_CONTEXTVAR_GET_METHODDEF    \
     {"get", (PyCFunction)_contextvars_ContextVar_get, METH_FASTCALL, _contextvars_ContextVar_get__doc__},
@@ -131,7 +148,13 @@ exit:
 PyDoc_STRVAR(_contextvars_ContextVar_set__doc__,
 "set($self, value, /)\n"
 "--\n"
-"\n");
+"\n"
+"Call to set a new value for the context variable in the current context.\n"
+"\n"
+"The required value argument is the new value for the context variable.\n"
+"\n"
+"Returns a Token object that can be used to restore the variable to its previous\n"
+"value via the `ContextVar.reset()` method.");
 
 #define _CONTEXTVARS_CONTEXTVAR_SET_METHODDEF    \
     {"set", (PyCFunction)_contextvars_ContextVar_set, METH_O, _contextvars_ContextVar_set__doc__},
@@ -139,8 +162,12 @@ PyDoc_STRVAR(_contextvars_ContextVar_set__doc__,
 PyDoc_STRVAR(_contextvars_ContextVar_reset__doc__,
 "reset($self, token, /)\n"
 "--\n"
-"\n");
+"\n"
+"Reset the context variable.\n"
+"\n"
+"The variable is reset to the value it had before the `ContextVar.set()` that\n"
+"created the token was used.");
 
 #define _CONTEXTVARS_CONTEXTVAR_RESET_METHODDEF    \
     {"reset", (PyCFunction)_contextvars_ContextVar_reset, METH_O, _contextvars_ContextVar_reset__doc__},
-/*[clinic end generated code: output=d9a675e3a52a14fc input=a9049054013a1b77]*/
+/*[clinic end generated code: output=33414d13716d0648 input=a9049054013a1b77]*/