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

tim-one · tim-one · commit a995a2dd54f9 · 2004-07-29T03:29:15.000Z
invariants they must satisfy.
diff --git 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;
 
