From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Sun, 22 Feb 2026 10:13:28 +0000 (+0200)
Subject: Expand documentation for opcodes 0-3: refined descriptions, enhanced usage notes... 
X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=c395b384afcda90a4da64e6f5b47317b3fdcc2a8;p=fifth.git

Expand documentation for opcodes 0-3: refined descriptions, enhanced usage notes, added implementation details, and clarified stack effects.
---

diff --git a/doc/opcodes_00_09.org b/doc/opcodes_00_09.org
index 242f989..0de3b7b 100644
--- a/doc/opcodes_00_09.org
+++ b/doc/opcodes_00_09.org
@@ -36,8 +36,10 @@
 - *Description:* No operation. The VM simply proceeds to the next
   instruction without modifying any state. This is a placeholder
   instruction that has no effect on registers or stacks.
-- *Notes:* Implemented by jumping back to the main instruction fetch
-  loop (=emu= label), effectively doing nothing.
+- *Implementation:* The opcode unconditionally triggers next instruction fetch within emulator,
+  effectively executing nothing.
+- *Usage Pattern:* Typically used for padding, aligning code segments,
+  or as a placeholder during code development.
 
 * 1: halt
 :PROPERTIES:
@@ -45,32 +47,45 @@
 :ID:       7c8841d3-2335-4ee9-b6b9-518d05354841
 :END:
 - *Stack Effect:* =--=
-- *Description:* Terminates the emulator process. Restores the original
-  text mode, closes the virtual disk file, restores the keyboard driver,
-  and exits to DOS.
-- *Notes:* This is the only way to cleanly exit the emulator. No stack
-  items are consumed.
+- *Description:* Terminates the emulator process cleanly. The halt
+  procedure performs the following sequence:
+  1. Restores text mode video mode (3)
+  2. Unmounts the virtual disk file
+  3. Calls =KB_restore= to restore the original keyboard interrupt handler
+  4. Exits to DOS with exit code 0
+
+- *Notes:* This is the ONLY way to cleanly exit the emulator.
 
 * 2: kbd@
 :PROPERTIES:
 :CUSTOM_ID: ID-820b1b90-4f4c-4ab1-b49f-9b4a52ea2528
 :ID:       820b1b90-4f4c-4ab1-b49f-9b4a52ea2528
 :END:
+
 - *Stack Effect:* =-- scancode=
 - *Description:* Reads the next keyboard scan code from the keyboard
-  buffer. Returns 0 if no keys are pressed. Non-blocking operation.
+  ring buffer and pushes it onto the data stack. If the buffer is empty,
+  pushes 0. This operation is non-blocking and does not wait for user
+  input.
+
+- *Timing Behavior:*
+  - Multiple =kbd@= calls in quick succession will return sequential
+    keys
+  - No blocking or timeout occurs if the buffer is empty
+  - Each key read consumes the key from the buffer permanently
 
 * 3: num
 :PROPERTIES:
 :CUSTOM_ID: ID-8721dc8c-b237-4e9a-a509-0ded1c02329b
 :ID:       8721dc8c-b237-4e9a-a509-0ded1c02329b
 :END:
+
 - *Stack Effect:* =-- n=
-- *Description:* Pushes a 32-bit immediate value onto the data stack.
-  The value is encoded in the instruction stream immediately after the
-  opcode.
-- *Notes:* The value is loaded from =[es:esi]=, then =esi= is
-  incremented by 4 to skip over the immediate data.
+- *Description:* Pushes a 32-bit immediate integer value onto the
+  data stack. The value is encoded directly in the instruction stream
+  following this opcode. After pushing, the instruction pointer
+  is advanced by 4 bytes to point to the next opcode.
+
 - *Example:*
   #+begin_example
   42  ; Push 42 onto stack