[Python-checkins] bpo-4260: Document that ctypes.xFUNCTYPE are decorators (GH-7924)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/08c1da71030e0d6019b3493e0ffaf060a6aa5d8e
commit: 08c1da71030e0d6019b3493e0ffaf060a6aa5d8e
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-07-13T06:35:31-07:00
summary:

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

(cherry picked from commit 379e9d639a52766f79c7a206c5096c8333d1896f)

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

files:
M Doc/library/ctypes.rst

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index edec764d640e..500aad8858f2 100644
--- 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
@@ -1577,7 +1593,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)