Document what the members of PyListObject are used for, and the crucial

invariants they must satisfy.

diff --git a/Include/listobject.h b/Include/listobject.h
index b4935ae89469e14c28a51066b1bdfb0dec7665c9..62a85180808ba20ab5abe14b91f264d8ffbea9d6 100644 (file)
--- a/Include/listobject.h
+++ b/Include/listobject.h
@@ -21,7 +21,16 @@ extern "C" {
 
 typedef struct {
     PyObject_VAR_HEAD
+    /* Vector of pointers to list elements.  list[0] is ob_item{0], etc. */
     PyObject **ob_item;
+
+    /* ob_item contains space for 'allocated' elements.  The number
+     * currently in use is ob_size.
+     * Invariants:
+     *     0 <= ob_size <= allocated
+     *     len(list) == ob_size
+     *     ob_item == NULL implies ob_size == allocated == 0
+     */
     int allocated;
 } PyListObject;