bpo-4260: Document that ctypes.xFUNCTYPE are decorators (GH-7924)

(cherry picked from commit 379e9d639a52766f79c7a206c5096c8333d1896f)

Co-authored-by: Andrés Delfino <adelfino@gmail.com>

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index cdcbefa4e8084af95e40d815778c022a13be501a..a7cc0c84df1b1ee1fabfccdbb627f337f48f979a 100644 (file)
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1025,6 +1025,22 @@ As we can easily check, our array is sorted now::
    1 5 7 33 99
    >>>
 
+The function factories can be used as decorator factories, so we may as well
+write::
+
+   >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
+   ... def py_cmp_func(a, b):
+   ...     print("py_cmp_func", a[0], b[0])
+   ...     return a[0] - b[0]
+   ...
+   >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
+   py_cmp_func 5 1
+   py_cmp_func 33 99
+   py_cmp_func 7 33
+   py_cmp_func 1 7
+   py_cmp_func 5 7
+   >>>
+
 .. note::
 
    Make sure you keep references to :func:`CFUNCTYPE` objects as long as they
@@ -1575,7 +1591,9 @@ Foreign functions can also be created by instantiating function prototypes.
 Function prototypes are similar to function prototypes in C; they describe a
 function (return type, argument types, calling convention) without defining an
 implementation.  The factory functions must be called with the desired result
-type and the argument types of the function.
+type and the argument types of the function, and can be used as decorator
+factories, and as such, be applied to functions through the ``@wrapper`` syntax.
+See :ref:`ctypes-callback-functions` for examples.
 
 
 .. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)