From 6dd1d51dd988a08a4d1de4ba6c04bb3edc492b7d Mon Sep 17 00:00:00 2001
From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Mon, 16 Feb 2026 01:40:51 +0200
Subject: [PATCH] Document and clarify `xminus` instruction in `emulator.asm`:
 added detailed comments describing stack operations and memory layout.

---
 emulator/emulator.asm | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/emulator/emulator.asm b/emulator/emulator.asm
index 751fd61..0f71d06 100644
--- a/emulator/emulator.asm
+++ b/emulator/emulator.asm
@@ -279,15 +279,39 @@ xplus:	mov	ebx, [es:edi]
 	add	[es:edi], ebx
 	jmp	emu
 
-xminus: mov	ebx, [es:edi]
-	add	edi, 4
-	sub	[es:edi], ebx
-	jmp	emu
 
-xmul:	mov	eax, [es:edi]
+xminus:
+; Subtract: ( n1 n2 -- n1-n2 )
+;
+; Pops the top two elements from the data stack, subtracts the top
+; element (n2) from the second element (n1), and pushes the result.
+;
+; In Fifth source code, this corresponds to the "-" word:
+;
+;     10 3 -       \ result is 7  (10 minus 3)
+;
+; Argument order:
+;   n1 is pushed first  (sits deeper in the stack, at [es:edi+4])
+;   n2 is pushed second (sits on top of the stack,  at [es:edi])
+;
+; Memory layout before execution:
+;   [es:edi]   = n2  (top of stack — the value being subtracted)
+;   [es:edi+4] = n1  (second on stack — the value subtracted from)
+;
+; Memory layout after execution:
+;   [es:edi]   = n1 - n2  (edi has been adjusted; old n2 slot is freed)
+
+    mov	ebx, [es:edi]	        ; ebx = n2 (the subtrahend — value to subtract)
+	add	edi, 4			        ; pop n2 off the stack; n1 is now the new top
+	sub	[es:edi], ebx		    ; [es:edi] = n1 - n2  (subtract n2 from n1 in place)
+	jmp	emu
+
+
+xmul:
+    mov	eax, [es:edi]
 	add	edi, 4
 	sub	edx, edx
-	imul	 dword [es:edi]
+	imul dword [es:edi]
 	mov	[es:edi], eax
 	jmp	emu
 
-- 
2.20.1