From dc3b1c898fcc010e5b38520b7dc315eff5e5eb6d Mon Sep 17 00:00:00 2001
From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Tue, 17 Feb 2026 01:27:48 +0200
Subject: [PATCH] Document and clarify stack operations in `emulator.asm`:
 added detailed comments for `xinc`, `xdec`, `xdup`, and `xdrop` describing
 stack effects and memory layouts.

---
 emulator/emulator.asm | 96 ++++++++++++++++++++++++++++++-------------
 1 file changed, 67 insertions(+), 29 deletions(-)

diff --git a/emulator/emulator.asm b/emulator/emulator.asm
index 0f71d06..4c8839e 100644
--- a/emulator/emulator.asm
+++ b/emulator/emulator.asm
@@ -70,7 +70,8 @@ shl	bx, 1
 add	bx, table
 jmp	word [cs:bx]
 
-table	dw emu		; 0
+table
+    dw emu		; 0
 	dw quit
 	dw xkbd@
 	dw xnum
@@ -99,25 +100,25 @@ table	dw emu		; 0
 	dw xmul
 	dw xdiv
 	dw xgreat
-	dw xless
-	dw xnot 	; 30
-	dw xi
-	dw xcprt@
-	dw xcprt!
-	dw xi2
-	dw xi3		; 35
-	dw xshl
-	dw xshr
-	dw lor
-	dw lxor
-	dw xvidmap	; 40
-	dw xmouse@
-	dw xvidput
-	dw xcmove
-	dw xcfill
-	dw xtvidput	; 45
-	dw xdep
-	dw xcharput
+    dw xless    ; 29
+    dw xnot     ; 30
+    dw xi       ; 31
+    dw xcprt@   ; 32
+    dw xcprt!   ; 33
+    dw xi2      ; 34
+    dw xi3      ; 35
+    dw xshl     ; 36
+    dw xshr     ; 37
+    dw lor      ; 38
+    dw lxor     ; 39
+    dw xvidmap  ; 40
+    dw xmouse@  ; 41
+    dw xvidput  ; 42
+    dw xcmove   ; 43
+    dw xcfill   ; 44
+    dw xtvidput ; 45
+    dw xdep     ; 46
+    dw xcharput ; 47
 
 xkbd@:	call	KB_read
 	sub	edi, 4
@@ -153,19 +154,56 @@ xcall:	mov	edx, dword [es:esi]
 	add	esi, [xms_addr]
 	jmp	emu
 
-xinc:	inc	dword [es:edi]
-	jmp	emu
+xinc: ; Increment: ( n -- n+1 )
+; Increments the top of the data stack by 1.
 
-xdec:	dec	dword [es:edi]
+    inc	dword [es:edi]
 	jmp	emu
 
-xdup:	mov	eax, [es:edi]
-	sub	edi, 4
-	mov	[es:edi], eax
-	jmp	emu
 
-xdrop:	add	edi, 4
-	jmp	emu
+xdec:  ; Decrement: ( n -- n-1 )
+;
+; Decrements the top of the data stack by 1.
+;
+; Memory layout before execution:
+;   [es:edi] = n
+;
+; Memory layout after execution:
+;   [es:edi] = n-1
+
+    dec dword [es:edi]  ; decrement the top of the stack
+    jmp emu
+
+
+xdup:  ; Duplicate: ( n -- n n )
+;
+; Duplicates the top element of the data stack.
+;
+; Memory layout before execution:
+;   [es:edi] = n
+;
+; Memory layout after execution:
+;   [es:edi]   = n (new top)
+;   [es:edi+4] = n (original top)
+
+    mov eax, [es:edi]   ; copy top element to eax
+    sub edi, 4      ; move stack pointer down to make space
+    mov [es:edi], eax   ; push copy of top element onto stack
+    jmp emu
+
+
+xdrop: ; Drop: ( n -- )
+;
+; Removes the top element from the data stack.
+;
+; Memory layout before execution:
+;   [es:edi] = n
+;
+; Memory layout after execution:
+;   Stack pointer is adjusted; n is no longer on stack
+
+    add edi, 4      ; pop top element off the stack
+    jmp emu
 
 xif:	mov	eax, [es:edi]
 	add	edi, 4
-- 
2.20.1