From a995a2dd54f904913bfde54317480edf3a3b79c8 Mon Sep 17 00:00:00 2001
From: Tim Peters <tim.peters@gmail.com>
Date: Thu, 29 Jul 2004 03:29:15 +0000
Subject: [PATCH] Document what the members of PyListObject are used for, and
 the crucial invariants they must satisfy.

---
 Include/listobject.h | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Include/listobject.h b/Include/listobject.h
index b4935ae8946..62a85180808 100644
--- 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;