Document and clarify `xminus` instruction in `emulator.asm`: added detailed comments...

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