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 b4935ae..62a8518 100644
--- a/Include/listobject.h
+++ b/Include/listobject.h
@@ -21,7 +21,16 @@
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;