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

invariants they must satisfy.

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;