From 8cb78fa4a0e6ce1ef1010bcf762d02dcb7ec7945 Mon Sep 17 00:00:00 2001
From: ZeroIntensity <zintensitydev@gmail.com>
Date: Sat, 22 Jun 2024 15:51:40 -0400
Subject: [PATCH] Add documentation for pyawaitable_await_function

---
 docs/adding_coros.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/adding_coros.md b/docs/adding_coros.md
index b0dfe81..502d1e7 100644
--- a/docs/adding_coros.md
+++ b/docs/adding_coros.md
@@ -102,6 +102,38 @@ spam(PyObject *self, PyObject *args)
 
 This would be equivalent to `await foo` from Python.
 
+Alternatively, you can use `pyawaitable_await_function` (`PyAwaitable_AwaitFunction` with the Python API prefixes), which behaves similarly to `PyObject_CallFunction`, in the sense that arguments are generated from a format string.
+
+Note that unlike, `pyawaitable_await`, `pyawaitable_await_function` takes a *callable* object, instead of a coroutine. For example:
+
+```c
+static PyObject *
+spam(PyObject *self, PyObject *func) // METH_O
+{
+    PyObject *awaitable = pyawaitable_new();
+
+    if (awaitable == NULL)
+        return NULL;
+
+    if (pyawaitable_await_function(awaitable, func, "s", NULL, NULL, "hello, world!") < 0)
+    {
+        Py_DECREF(awaitable);
+        return NULL;
+    }
+
+    return awaitable;
+}
+```
+
+This would be equivalent to the following Python code:
+
+```py
+async def func(data: str) -> Any:
+    ...
+
+await func("hello, world!")
+```
+
 ## Return Values
 
 You can set a return value (the thing that `await c_func()` will evaluate to) via `pyawaitable_set_result` (`PyAwaitable_SetResult` in the Python prefixes). By default, the return value is `None`.