1 files changed, 20 insertions, 0 deletions
diff --git a/Include/weakrefobject.h b/Include/weakrefobject.h
index 3503892e0e..daf490f50c 100644
--- a/Include/weakrefobject.h
+++ b/Include/weakrefobject.h
@@ -9,11 +9,31 @@ extern "C" {
 
 typedef struct _PyWeakReference PyWeakReference;
 
+/* PyWeakReference is the base struct for the Python ReferenceType, ProxyType,
+ * and CallableProxyType.
+ */
 struct _PyWeakReference {
     PyObject_HEAD
+
+    /* The object to which this is a weak reference, or Py_None if none.
+     * Note that this is a stealth reference:  wr_object's refcount is
+     * not incremented to reflect this pointer.
+     */
     PyObject *wr_object;
+
+    /* A callable to invoke when wr_object dies, or NULL if none. */
     PyObject *wr_callback;
+
+    /* A cache for wr_object's hash code.  As usual for hashes, this is -1
+     * if the hash code isn't known yet.
+     */
     long hash;
+
+    /* If wr_object is weakly referenced, wr_object has a doubly-linked NULL-
+     * terminated list of weak references to it.  These are the list pointers.
+     * If wr_object goes away, wr_object is set to Py_None, and these pointers
+     * have no meaning then.
+     */
     PyWeakReference *wr_prev;
     PyWeakReference *wr_next;
 };