Comment on the set_swap_bodies() helper function.

diff --git a/Objects/setobject.c b/Objects/setobject.c
index e922b6ef539891ee725d3fc4c67aa6db3d9c877d..a279ec2a5ced7976352f10c9c21c80de9ee646f7 100644 (file)
--- a/Objects/setobject.c
+++ b/Objects/setobject.c
@@ -793,6 +793,19 @@ set_len(PyObject *so)
        return ((PySetObject *)so)->used;
 }
 
+/* set_swap_bodies() switches the contents of any two sets by moving their
+   internal data pointers and, if needed, copying the internal smalltables.
+   Semantically equivalent to:
+
+     t=set(a); a.clear(); a.update(b); b.clear(); b.update(t); del t
+
+   The function always succeeds and it leaves both objects in a stable state.
+   Useful for creating temporary frozensets from sets for membership testing 
+   in __contains__(), discard(), and remove().  Also useful for operations
+   that update in-place (by allowing an intermediate result to be swapped 
+   into one of original the inputs).
+*/
+
 static void
 set_swap_bodies(PySetObject *a, PySetObject *b)
 {