update layout comment per pr suggestion

clintonsteiner · clintonsteiner · commit 27b3fa0bee36 · 2026-02-22T06:58:55.000-06:00
diff --git a/Include/internal/pycore_dict.h b/Include/internal/pycore_dict.h
@@ -171,7 +171,9 @@ typedef enum {
     DICT_KEYS_SPLIT = 2
 } DictKeysKind;
 
-/* See dictobject.c for actual layout of DictKeysObject */
+/* See dictobject.c for the full DictKeysObject memory layout.
+ * A PyDictKeysObject* points to the fixed-size header below.
+ */
 struct _dictkeysobject {
     Py_ssize_t dk_refcnt;
 
@@ -211,7 +213,8 @@ struct _dictkeysobject {
        - 4 bytes if dk_size <= 0xffffffff (int32_t*)
        - 8 bytes otherwise (int64_t*)
 
-       Dynamically sized, SIZEOF_VOID_P is minimum. */
+       Dynamically sized. This is the start of the variable-sized tail that
+       immediately follows the fixed-size header. */
     char dk_indices[];  /* char is required to avoid strict aliasing. */
 
     /* "PyDictKeyEntry or PyDictUnicodeEntry dk_entries[USABLE_FRACTION(DK_SIZE(dk))];" array follows:
diff --git a/Objects/dictobject.c b/Objects/dictobject.c
@@ -17,6 +17,7 @@ As of Python 3.6, this is compact and ordered. Basic idea is described here:
 layout:
 
 +---------------------+
+| struct _dictkeysobj |
 | dk_refcnt           |
 | dk_log2_size        |
 | dk_log2_index_bytes |
@@ -25,13 +26,17 @@ As of Python 3.6, this is compact and ordered. Basic idea is described here:
 | dk_usable           |
 | dk_nentries         |
 +---------------------+
-| dk_indices[]        |
+| dk_indices[]        |  <-- starts at &dk->dk_indices[0]
 |                     |
 +---------------------+
-| dk_entries[]        |
+| dk_entries[]        |  <-- starts at DK_ENTRIES(dk)
 |                     |
 +---------------------+
 
+A PyDictKeysObject* points to the start of the fixed-size header.
+The variable-sized part begins at dk_indices and is followed immediately by
+the entry array.
+
 dk_indices is actual hashtable.  It holds index in entries, or DKIX_EMPTY(-1)
 or DKIX_DUMMY(-2).
 Size of indices is dk_size.  Type of each index in indices varies with dk_size:
