--- a/src/lwbasic.s	Sat Dec 10 00:37:32 2022 -0700
+++ b/src/lwbasic.s	Sun Dec 11 21:33:25 2022 -0700
@@ -245,6 +245,26 @@
                 endc
 textscreen      rmb 0x200                       ; the actual text screen (must be on 512 byte alignment)
 heapstart       equ *                           ; start of dynamically allocated stuff
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; The heap has the following items in order:
+;
+; Program text: preceded by a NUL and pointed to by progtext
+; Variable table: pointed to by vartab; contains records for all scalar and array variables
+; Free space: unused memory between the object table and the stack; pointed to by freestart
+; The stack: grows downward from the bottom of string space, pointed to by the stack pointer, obviously
+; String space: garbage collected non-constant string data pointed to by freetop
+; Reserved memory: immediately above string space; pointed to by memsize
+; Actual top of RAM: top of reserved memory; pointed to by memtop
+;
+; The variable table consists of several symbol tables defined as follows:
+;
+; Pointer       Size of entry   Variable types
+; vartabint     4               Integer scalars
+; vartablong    6               Long integer scalars
+; vartabfloat   7               Floating point scalars
+; vartabstring  6               String scalars
+;
+; Each entry starts with 2 bytes for the variable name followed by the data payload.
                 org 0x8000                      ; the hardware puts the ROMs here; it's not negotiable
 ROMSTART        equ *
 START           orcc #0x50                      ; make sure interrupts are disabled if we come here in an unusual way