Added tons of AI generated docs and a lot of cleanups. No code changes. (0.41.5)

src/vm/arithmetic/div.c

@@ -9,24 +9,28 @@
 
 /**
  * @file div.c
- * @brief Implements the OP_DIV opcode for integer division in the VM.
+ * @brief Implements the OP_DIV opcode (numeric division) in the VM.
  *
- * This file handles the OP_DIV instruction, which performs integer division
- * on two integer values popped from the stack and pushes the result back onto the stack.
+ * Handles the OP_DIV instruction, dividing two numeric operands and pushing
+ * the result. If either operand is a float, division is performed in double
+ * precision and a VAL_FLOAT is produced; otherwise integer division is
+ * used and a VAL_INT is produced.
  *
  * Behavior:
- * - Pops two integer values from the stack.
- * - Performs integer division (`a / b`).
- * - Pushes the result back onto the stack.
+ * - Pops two values from the stack.
+ * - If any operand is VAL_FLOAT, computes (double)a / (double)b and pushes a VAL_FLOAT.
+ * - Else computes a.i / b.i and pushes a VAL_INT.
  *
  * Error Handling:
- * - Exits with an error if the operands are not integers.
- * - Exits with an error if division by zero is attempted.
+ * - Raises a runtime error and aborts execution if operands are not numeric.
+ * - Raises a runtime error on division by zero (both integer and floating cases).
  *
  * Example:
  * // Bytecode: OP_DIV
  * // Stack before: [10, 2]
  * // Stack after: [5]
+ * // Stack before: [5.0, 2]
+ * // Stack after: [2.5]
  *
  * @author Johannes Findeisen
  * @date 2025-10-16

src/vm/arithmetic/mul.c

@@ -9,23 +9,27 @@
 
 /**
  * @file mul.c
- * @brief Implements the OP_MUL opcode for integer multiplication in the VM.
+ * @brief Implements the OP_MUL opcode (numeric multiplication) in the VM.
  *
- * This file handles the OP_MUL instruction, which performs integer multiplication
- * on two integer values popped from the stack and pushes the result back onto the stack.
+ * Handles the OP_MUL instruction, multiplying two numeric operands and
+ * pushing the result. If either operand is a float, multiplication is
+ * performed in double precision; otherwise it is 64-bit integer
+ * multiplication.
  *
  * Behavior:
- * - Pops two integer values from the stack.
- * - Performs integer multiplication (`a * b`).
- * - Pushes the result back onto the stack.
+ * - Pops two values from the stack.
+ * - If any operand is VAL_FLOAT, computes (double)a * (double)b and pushes a VAL_FLOAT.
+ * - Else computes a.i * b.i and pushes a VAL_INT.
  *
  * Error Handling:
- * - Exits with an error if the operands are not integers.
+ * - Raises a runtime error and aborts execution if operands are not numeric.
  *
  * Example:
  * // Bytecode: OP_MUL
  * // Stack before: [3, 4]
  * // Stack after: [12]
+ * // Stack before: [2.5, 4]
+ * // Stack after: [10.0]
  *
  * @author Johannes Findeisen
  * @date 2025-10-16

src/vm/arithmetic/sub.c

@@ -9,23 +9,27 @@
 
 /**
  * @file sub.c
- * @brief Implements the OP_SUB opcode for integer subtraction in the VM.
+ * @brief Implements the OP_SUB opcode (numeric subtraction) in the VM.
  *
- * This file handles the OP_SUB instruction, which performs integer subtraction
- * on two integer values popped from the stack and pushes the result back onto the stack.
+ * Handles the OP_SUB instruction, subtracting two numeric operands and
+ * pushing the result. If either operand is a float, subtraction is
+ * performed in double precision; otherwise it is 64-bit integer
+ * subtraction.
  *
  * Behavior:
- * - Pops two integer values from the stack.
- * - Performs integer subtraction (`a - b`).
- * - Pushes the result back onto the stack.
+ * - Pops two values from the stack.
+ * - If any operand is VAL_FLOAT, computes (double)a - (double)b and pushes a VAL_FLOAT.
+ * - Else computes a.i - b.i and pushes a VAL_INT.
  *
  * Error Handling:
- * - Exits with an error if the operands are not integers.
+ * - Raises a runtime error and aborts execution if operands are not numeric.
  *
  * Example:
  * // Bytecode: OP_SUB
  * // Stack before: [10, 4]
  * // Stack after: [6]
+ * // Stack before: [10.0, 3]
+ * // Stack after: [7.0]
  *
  * @author Johannes Findeisen
  * @date 2025-10-16

src/vm/arrays/clear.c

@@ -8,26 +8,27 @@
  */
 
 /**
-* @file clear.c
+ * @file clear.c
  * @brief Implements the OP_CLEAR opcode for clearing arrays in the VM.
- *
- * This file handles the OP_CLEAR instruction, which clears all elements from an array.
- * The array is popped from the stack, and nothing is pushed back.
- *
+
+ * Handles the OP_CLEAR instruction, which removes all elements from an array.
+ * The array is popped from the stack; the opcode pushes an integer result
+ * (currently 0) as an acknowledgement.
+
  * Behavior:
  * - Pops the array from the stack.
- * - Clears all elements from the array.
- *
- * Error Handling:
- * - Exits with an error if the array is of the wrong type.
- *
- * Example:
+ * - Clears all elements from the array (array becomes empty in place).
+ * - Pushes 0 (integer) to acknowledge success.
 
+ * Error Handling:
+ * - Exits with a runtime error if the operand is not an array.
+
+ * Example:
  * // Bytecode: OP_CLEAR
  * // Stack before: [[10, 20, 30]]
- * // Stack after: []
- *
- * @author Johannes Findeise
+ * // Stack after: [0]
+
+ * @author Johannes Findeisen
  * @date 2025-10-16
  */
 

src/vm/arrays/make_array.c

@@ -28,7 +28,7 @@
  * // Stack before: [1, 2, 3]
  * // Stack after: [[1, 2, 3]]
  *
- * @author Johanes Findeisen
+ * @author Johannes Findeisen
  * @date 2025-10-16
  */
 

src/vm/arrays/push.c

@@ -8,11 +8,12 @@
  */
 
 /**
- * @file arr_push.c
- * @brief Implements the OP_ARR_PUSH opcode for appending elements to arrays in the VM.
+ * @file push.c
+ * @brief Implements the OP_PUSH opcode for appending elements to arrays in the VM.
  *
- * This file handles the OP_ARR_PUSH instruction, which appends a value to the end of an array.
- * The array and value are popped from the stack, and the new length of the array is pushed back onto the stack.
+ * Handles the OP_PUSH instruction, which appends a value to the end of an array.
+ * The array and value are popped from the stack; the opcode pushes the new array
+ * length (integer) as a result.
  *
  * Behavior:
  * - Pops the value and array from the stack.
@@ -20,11 +21,11 @@
  * - Pushes the new length of the array onto the stack.
  *
  * Error Handling:
- * - Exits with an error if the array is of the wrong type.
- * - Exits with an error if memory allocation fails during the append operation.
+ * - Exits with a runtime error if the first operand is not an array.
+ * - Exits with a runtime error if memory allocation fails.
  *
  * Example:
- * // Bytecode: OP_ARR_PUSH
+ * // Bytecode: OP_PUSH
  * // Stack before: [42, [10, 20, 30]]
  * // Stack after: [4]
  *

src/vm/arrays/remove.c

@@ -8,11 +8,11 @@
  */
 
 /**
- * @file arr_remove.c
- * @brief Implements the OP_ARR_REMOVE opcode for removing elements from arrays in the VM.
+ * @file remove.c
+ * @brief Implements the OP_REMOVE opcode for removing elements from arrays in the VM.
  *
- * This file handles the OP_ARR_REMOVE instruction, which removes an element from an array
- * at a specified index. The array and index are popped from the stack, and the removed
+ * Handles the OP_REMOVE instruction, which removes an element from an array at the
+ * specified index. The array and index are popped from the stack; the removed
  * element is pushed back onto the stack.
  *
  * Behavior:
@@ -21,11 +21,11 @@
  * - Pushes the removed element onto the stack.
  *
  * Error Handling:
- * - Exits with an error if the array or index is of the wrong type.
- * - Exits with an error if the index is out of bounds.
+ * - Exits with a runtime error if the container is not an array or index is not an int.
+ * - Exits with a runtime error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_ARR_REMOVE
+ * // Bytecode: OP_REMOVE
  * // Stack before: [1, [10, 20, 30]]
  * // Stack after: [20]
  *

src/vm/arrays/set.c

@@ -8,23 +8,24 @@
  */
 
 /**
- * @file arr_set.c
- * @brief Implements the OP_ARR_SET opcode for setting elements in arrays in the VM.
+ * @file set.c
+ * @brief Implements the OP_SET opcode for setting elements in arrays in the VM.
  *
- * This file handles the OP_ARR_SET instruction, which sets a value at a specified index in an array.
- * The value, index, and array are popped from the stack, and the value is pushed back onto the stack.
+ * Handles the OP_SET instruction, which sets a value at a specified index in an array.
+ * The value, index, and array are popped from the stack; the value is returned back
+ * on the stack (as a copy) to mirror expression semantics.
  *
  * Behavior:
  * - Pops the value, index, and array from the stack.
  * - Sets the value at the specified index in the array.
- * - Pushes the value back onto the stack.
+ * - Pushes a copy of the value back onto the stack.
  *
  * Error Handling:
- * - Exits with an error if the array or index is of the wrong type.
- * - Exits with an error if the index is out of bounds.
+ * - Exits with a runtime error if the array or index is of the wrong type.
+ * - Exits with a runtime error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_ARR_SET
+ * // Bytecode: OP_SET
  * // Stack before: [42, 1, [10, 20, 30]]
  * // Stack after: [42]
  *

src/vm/bitwise/band.c

@@ -5,14 +5,28 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-09-29
  */
 
+ /**
+  * @file band.c
+  * @brief Implements the OP_BAND opcode (bitwise AND).
+  *
+  * Opcode snippet included by vm.c. Performs a 32-bit unsigned bitwise AND
+  * on two integer operands from the VM stack.
+  */
+
 /**
- * OP_BAND: bitwise AND (uint32 32-bit)
- * pops: b, a
- * pushes: (uint32_t)(a & b)
+ * OP_BAND: bitwise AND (uint32)
+ *
+ * Stack effects:
+ *  - pops: b, a
+ *  - pushes: (uint32_t)(a & b)
+ *
+ * Notes:
+ *  - Operands are interpreted as 32-bit unsigned when of type VAL_INT;
+ *    non-integer values are treated as 0.
+ *  - The result is pushed as VAL_INT with the 32-bit value preserved in the
+ *    low bits.
  */
 case OP_BAND: {
   Value vb = pop_value(vm);

src/vm/bitwise/bnot.c

@@ -5,14 +5,28 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-09-29
  */
 
+ /**
+  * @file bnot.c
+  * @brief Implements the OP_BNOT opcode (bitwise NOT).
+  *
+  * Opcode snippet included by vm.c. Performs a 32-bit unsigned bitwise NOT
+  * on a single integer operand from the VM stack.
+  */
+
 /**
- * OP_BNOT: bitwise NOT (uint32 32-bit)
- * pops: a
- * pushes: (uint32_t)(~a)
+ * OP_BNOT: bitwise NOT (uint32)
+ *
+ * Stack effects:
+ *  - pops: a
+ *  - pushes: (uint32_t)(~a)
+ *
+ * Notes:
+ *  - Operand is interpreted as 32-bit unsigned when of type VAL_INT;
+ *    non-integer values are treated as 0.
+ *  - The result is pushed as VAL_INT with the 32-bit value preserved in the
+ *    low bits.
  */
 case OP_BNOT: {
   Value va = pop_value(vm);

src/vm/bitwise/bor.c

@@ -5,14 +5,28 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-09-29
  */
 
+ /**
+  * @file bor.c
+  * @brief Implements the OP_BOR opcode (bitwise OR).
+  *
+  * Opcode snippet included by vm.c. Performs a 32-bit unsigned bitwise OR
+  * on two integer operands from the VM stack.
+  */
+
 /**
- * OP_BOR: bitwise OR (uint32 32-bit)
- * pops: b, a
- * pushes: (uint32_t)(a | b)
+ * OP_BOR: bitwise OR (uint32)
+ *
+ * Stack effects:
+ *  - pops: b, a
+ *  - pushes: (uint32_t)(a | b)
+ *
+ * Notes:
+ *  - Operands are interpreted as 32-bit unsigned when of type VAL_INT;
+ *    non-integer values are treated as 0.
+ *  - The result is pushed as VAL_INT with the 32-bit value preserved in the
+ *    low bits.
  */
 case OP_BOR: {
   Value vb = pop_value(vm);

src/vm/bitwise/bxor.c

@@ -5,14 +5,28 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-09-29
  */
 
 /**
- * OP_BXOR: bitwise XOR (uint32 32-bit)
- * pops: b, a
- * pushes: (uint32_t)(a ^ b)
+ * @file bxor.c
+ * @brief Implements the OP_BXOR opcode (bitwise XOR).
+ *
+ * This file is an opcode snippet included by vm.c. It implements a
+ * 32-bit unsigned bitwise XOR of two integer operands from the VM stack.
+ */
+
+/**
+ * OP_BXOR: bitwise XOR (uint32)
+ *
+ * Stack effects:
+ *  - pops: b, a
+ *  - pushes: (uint32_t)(a ^ b)
+ *
+ * Notes:
+ *  - Operands are taken as 32-bit unsigned integers when of type VAL_INT;
+ *    non-integer values are treated as 0.
+ *  - Result is pushed back as VAL_INT, preserving 32-bit value in the
+ *    low bits of the 64-bit integer storage.
  */
 case OP_BXOR: {
   Value vb = pop_value(vm);

src/vm/bitwise/rol.c

@@ -5,14 +5,27 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file rol.c
+ * @brief Implements the OP_ROTL opcode (rotate-left).
  *
- * Added: 2025-09-29
+ * Opcode snippet included by vm.c. Performs a 32-bit unsigned rotate-left of
+ * an integer operand by a masked rotation count.
  */
 
 /**
  * OP_ROTL: rotate left (uint32)
- * pops: s, a
- * pushes: rotl32(a, s)
+ *
+ * Stack effects:
+ *  - pops: s, a
+ *  - pushes: (a << s) | (a >> (32 - s)), with s masked to 0..31
+ *
+ * Notes:
+ *  - Both a (value) and s (count) are taken from VAL_INT; non-integers are 0.
+ *  - The rotation count is masked to 0..31. A zero rotation returns a unchanged.
+ *  - Result is pushed as VAL_INT with the 32-bit value preserved in the low bits.
  */
 case OP_ROTL: {
   Value vs = pop_value(vm);

src/vm/bitwise/ror.c

@@ -5,14 +5,27 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file ror.c
+ * @brief Implements the OP_ROTR opcode (rotate-right).
  *
- * Added: 2025-09-29
+ * Opcode snippet included by vm.c. Performs a 32-bit unsigned rotate-right of
+ * an integer operand by a masked rotation count.
  */
 
 /**
  * OP_ROTR: rotate right (uint32)
- * pops: s, a
- * pushes: rotr32(a, s)
+ *
+ * Stack effects:
+ *  - pops: s, a
+ *  - pushes: (a >> s) | (a << (32 - s)), with s masked to 0..31
+ *
+ * Notes:
+ *  - Both a (value) and s (count) are taken from VAL_INT; non-integers are 0.
+ *  - The rotation count is masked to 0..31. A zero rotation returns a unchanged.
+ *  - Result is pushed as VAL_INT with the 32-bit value preserved in the low bits.
  */
 case OP_ROTR: {
   Value vs = pop_value(vm);

src/vm/bitwise/shl.c

@@ -5,14 +5,27 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file shl.c
+ * @brief Implements the OP_SHL opcode (logical left shift).
  *
- * Added: 2025-09-29
+ * Opcode snippet included by vm.c. Performs a 32-bit unsigned logical left
+ * shift of an integer operand by a masked shift count.
  */
 
 /**
  * OP_SHL: logical left shift (uint32)
- * pops: s, a
- * pushes: (uint32_t)(a << (s&31))
+ *
+ * Stack effects:
+ *  - pops: s, a
+ *  - pushes: (uint32_t)(a << (s & 31))
+ *
+ * Notes:
+ *  - Both a (value) and s (shift) are taken from VAL_INT; non-integers are 0.
+ *  - The shift count is masked to 0..31. A zero shift returns a unchanged.
+ *  - Result is pushed as VAL_INT with the 32-bit value preserved in the low bits.
  */
 case OP_SHL: {
   Value vs = pop_value(vm);

src/vm/bitwise/shr.c

@@ -5,14 +5,28 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file shr.c
+ * @brief Implements the OP_SHR opcode (logical right shift).
  *
- * Added: 2025-09-29
+ * Opcode snippet included by vm.c. Performs a 32-bit unsigned logical right
+ * shift of an integer operand by a masked shift count.
  */
 
 /**
  * OP_SHR: logical right shift (uint32)
- * pops: s, a
- * pushes: (uint32_t)(a >> (s&31)) using logical shift
+ *
+ * Stack effects:
+ *  - pops: s, a
+ *  - pushes: (uint32_t)(a >> (s & 31))
+ *
+ * Notes:
+ *  - Both a (value) and s (shift) are taken from VAL_INT; non-integers are 0.
+ *  - The shift count is masked to 0..31. A zero shift returns a unchanged.
+ *  - Logical (zero-filling) right shift is used (no sign extend).
+ *  - Result is pushed as VAL_INT with the 32-bit value preserved in the low bits.
  */
 case OP_SHR: {
   Value vs = pop_value(vm);

src/vm/core/throw.c

@@ -7,6 +7,32 @@
  * https://opensource.org/license/apache-2-0
  */
 
+/**
+ * @file throw.c
+ * @brief Implements the OP_THROW opcode for raising exceptions in the VM.
+ *
+ * This file handles the OP_THROW instruction, which raises an exception. If a
+ * matching TRY handler exists in the current frame (pushed via OP_TRY_PUSH),
+ * control flow jumps to the handler location and the error value is made
+ * available to the catch block via the stack. If no handler is present in the
+ * current frame, the error is printed and the VM terminates execution by
+ * clearing the frame stack.
+ *
+ * Behavior:
+ * - Pops the error `Value` from the stack.
+ * - If the current frame has a pending TRY handler (f->try_sp >= 0):
+ *   - Retrieves the handler target IP from the TRY instruction's operand.
+ *   - Pushes the error back on the stack for the catch block to consume.
+ *   - Sets the instruction pointer (IP) to the handler target.
+ * - Otherwise (no handler):
+ *   - Prints the error in a human-readable form.
+ *   - Frees the error value and clears all frames (vm->fp = -1) to stop the VM.
+ *
+ * Errors:
+ * - None explicitly thrown here; if unhandled, the VM stops after printing the
+ *   error message.
+ */
+
 case OP_THROW: {
   Value err = pop_value(vm);
   /* if there is a handler in this frame, jump to it and push err for catch */

src/vm/core/try_pop.c

@@ -7,6 +7,22 @@
  * https://opensource.org/license/apache-2-0
  */
 
+/**
+ * @file try_pop.c
+ * @brief Implements the OP_TRY_POP opcode to end a try/catch region.
+ *
+ * This file handles the OP_TRY_POP instruction, which marks the end of the
+ * most recently started try/catch region in the current frame by popping its
+ * entry from the per-frame TRY stack.
+ *
+ * Behavior:
+ * - If f->try_sp >= 0, decrements f->try_sp (pops one TRY region).
+ * - Does not modify the value stack.
+ *
+ * Errors:
+ * - None; popping when no TRY is active is a no-op.
+ */
+
 case OP_TRY_POP: {
   if (f->try_sp >= 0) f->try_sp--;
   break;

src/vm/core/try_push.c

@@ -7,6 +7,25 @@
  * https://opensource.org/license/apache-2-0
  */
 
+/**
+ * @file try_push.c
+ * @brief Implements the OP_TRY_PUSH opcode to begin a try/catch region.
+ *
+ * This file handles the OP_TRY_PUSH instruction, which marks the start of a
+ * try/catch region in the current frame by pushing the index of the TRY
+ * instruction onto a small per-frame stack. The actual catch target IP is
+ * stored in the TRY instruction's operand and may be patched later by the
+ * compiler/linker.
+ *
+ * Behavior:
+ * - Pushes the index of this TRY instruction (f->ip - 1) onto f->try_stack.
+ * - Does not modify the value stack.
+ *
+ * Errors:
+ * - If the try depth exceeds the size of f->try_stack, prints a runtime error
+ *   and terminates the process.
+ */
+
 case OP_TRY_PUSH: {
   /* push index of this TRY instruction; handler ip is in its operand (may be patched later) */
   if (f->try_sp >= (int)(sizeof(f->try_stack) / sizeof(f->try_stack[0])) - 1) {

src/vm/cpp/add.cpp

@@ -1,17 +1,26 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-29
  */
 
-/*
- * Minimal C++ opcode for Fun VM — cpp_add
- * Build is gated by -DFUN_WITH_CPP=ON (see CMake).
+/**
+ * @file add.cpp
+ * @brief Fun VM C++ opcode snippet: add two 64-bit integers (cpp_add).
+ *
+ * This opcode is compiled and linked only when the CMake option
+ * `-DFUN_WITH_CPP=ON` is enabled. It demonstrates how to implement a
+ * VM opcode in C++ while exposing a C ABI symbol for the VM dispatcher.
+ *
+ * Stack behavior:
+ * - Pops: b:int64, a:int64
+ * - Pushes: (a + b):int64
+ *
+ * Error handling and type conversions (e.g., from other numeric types to
+ * int64) are delegated to the VM helpers `vm_pop_i64` and `vm_push_i64`.
  */
 
 #include <cstdint>
@@ -20,6 +29,21 @@ extern "C" {
 #include "vm.h" // C header; provides VM, vm_pop_i64, vm_push_i64
 }
 
+/**
+ * @brief Add two 64-bit integers from the VM stack and push the sum.
+ *
+ * Pops two values from the VM stack using `vm_pop_i64`, adds them as
+ * 64-bit signed integers, and pushes the result via `vm_push_i64`.
+ *
+ * Stack effect:
+ * - Input:  [..., a:int64, b:int64]
+ * - Output: [..., (a+b):int64]
+ *
+ * @param vm Pointer to the VM instance. Must not be NULL.
+ * @return 0 on success. Any stack underflow or conversion errors are
+ *         handled by the VM helpers; non-zero may be used by future
+ *         implementations to indicate a runtime error.
+ */
 extern "C" int fun_op_cpp_add(VM *vm) {
   int64_t a = vm_pop_i64(vm);
   int64_t b = vm_pop_i64(vm);

src/vm/curl/download.c

@@ -1,5 +1,41 @@
 /**
- * libcurl DOWNLOAD builtin
+ * This file is part of the Fun programming language.
+ * https://fun-lang.xyz/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the Apache-2.0 license.
+ * https://opensource.org/license/apache-2-0
+ */
+ 
+/**
+ * @file download.c
+ * @brief Fun VM opcode snippet: HTTP download to file via libcurl (OP_CURL_DOWNLOAD).
+ *
+ * This snippet is included by vm.c and implements the OP_CURL_DOWNLOAD
+ * instruction. When FUN_WITH_CURL is enabled, it downloads the content at
+ * the given URL and writes it to the specified filesystem path.
+ *
+ * Stack behavior:
+ * - Pops: path:string, url:string (values are converted via value_to_string_alloc)
+ * - Pushes: int (1 on success, 0 on error or when CURL is disabled)
+ *
+ * Error handling:
+ * - Returns 0 if URL/path conversion fails, file open fails, CURL init
+ *   or perform fails.
+ * - Follows redirects (CURLOPT_FOLLOWLOCATION = 1L).
+ * - Writes via fun_curl_file_write_cb directly into the opened FILE*.
+ *
+ * Notes:
+ * - All temporary allocations (URL, path) are freed; FILE* is closed.
+ * - On builds without FUN_WITH_CURL, consumes two values and pushes 0.
+ */
+/**
+ * @brief Opcode handler for OP_CURL_DOWNLOAD.
+ *
+ * Pops a destination path and URL, streams the HTTP response body
+ * into the file, and pushes 1 on success or 0 on any error. Without
+ * FUN_WITH_CURL, behaves as a no-op that consumes two values and
+ * pushes 0.
  */
 case OP_CURL_DOWNLOAD: {
 #ifdef FUN_WITH_CURL

src/vm/curl/get.c

@@ -1,5 +1,42 @@
 /**
- * libcurl GET builtin
+ * This file is part of the Fun programming language.
+ * https://fun-lang.xyz/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the Apache-2.0 license.
+ * https://opensource.org/license/apache-2-0
+ */
+ 
+/**
+ * @file get.c
+ * @brief Fun VM opcode snippet: HTTP GET via libcurl (OP_CURL_GET).
+ *
+ * This snippet is included by vm.c and implements the OP_CURL_GET
+ * instruction. When FUN_WITH_CURL is enabled, it performs an HTTP GET
+ * request for the provided URL and pushes the response body as a string.
+ * If libcurl support is not built in, or an error occurs, an empty string
+ * is pushed instead.
+ *
+ * Stack behavior:
+ * - Pops: url:string (any value is converted via value_to_string_alloc)
+ * - Pushes: body:string ("" on error or when CURL is disabled)
+ *
+ * Error handling:
+ * - If URL conversion fails or CURL initialization/performance fails,
+ *   the opcode pushes an empty string.
+ * - Follows HTTP redirects (CURLOPT_FOLLOWLOCATION = 1L).
+ *
+ * Notes:
+ * - Uses FunCurlBuf and fun_curl_write_cb from the curl extension helpers.
+ * - Memory allocated for temporary strings and buffers is freed before exit.
+ */
+/**
+ * @brief Opcode handler for OP_CURL_GET.
+ *
+ * Converts the top stack value to a URL string, issues a GET request
+ * using libcurl, and pushes the response body as a string. When
+ * compiled without FUN_WITH_CURL, the opcode becomes a no-op that
+ * consumes one value and pushes an empty string.
  */
 case OP_CURL_GET: {
 #ifdef FUN_WITH_CURL

src/vm/curl/post.c

@@ -1,5 +1,42 @@
 /**
- * libcurl POST builtin
+ * This file is part of the Fun programming language.
+ * https://fun-lang.xyz/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the Apache-2.0 license.
+ * https://opensource.org/license/apache-2-0
+ */
+ 
+/**
+ * @file post.c
+ * @brief Fun VM opcode snippet: HTTP POST via libcurl (OP_CURL_POST).
+ *
+ * This snippet is included by vm.c and implements the OP_CURL_POST
+ * instruction. When FUN_WITH_CURL is enabled, it performs an HTTP POST
+ * to the given URL with the provided request body and pushes the response
+ * body as a string. If libcurl support is not built in, or an error occurs,
+ * an empty string is pushed instead.
+ *
+ * Stack behavior:
+ * - Pops: body:string, url:string (values are converted via value_to_string_alloc)
+ * - Pushes: body:string (server response; "" on error or when CURL is disabled)
+ *
+ * Error handling:
+ * - If URL conversion fails, the opcode pushes an empty string and discards
+ *   any converted body.
+ * - Follows redirects (CURLOPT_FOLLOWLOCATION = 1L).
+ * - Sets CURLOPT_POST=1L and CURLOPT_POSTFIELDS to submit the body.
+ *
+ * Notes:
+ * - Uses FunCurlBuf and fun_curl_write_cb from the curl extension helpers.
+ * - All temporary allocations (URL, body, response buffer) are freed.
+ */
+/**
+ * @brief Opcode handler for OP_CURL_POST.
+ *
+ * Pops the POST body and URL, performs an HTTP POST, and pushes the
+ * response as a string. Without FUN_WITH_CURL, consumes two values and
+ * pushes an empty string.
  */
 case OP_CURL_POST: {
 #ifdef FUN_WITH_CURL

src/vm/echo.c

@@ -1,4 +1,4 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
@@ -8,11 +8,21 @@
  */
 
 /**
- * Implements OP_ECHO: print top-of-stack value without trailing newline.
- * Now stores the value into the VM's output buffer and marks it as partial,
- * so the CLI can render echo output together with following print output.
+ * @file echo.c
+ * @brief Implements the OP_ECHO opcode for printing without a trailing newline.
+ *
+ * This snippet is included into the VM dispatch loop and handles OP_ECHO.
+ * It pops the top value from the stack and appends it to the VM's output buffer
+ * but marks the entry as partial so that subsequent OP_PRINT may continue the
+ * same line.
+ *
+ * Stack contract:
+ * - Pops: value (any)
+ * - Pushes: (none)
  */
 
+/* Implements OP_ECHO: print top-of-stack value without trailing newline. */
+
 case OP_ECHO: {
   Value v = pop_value(vm);
   Value snap = deep_copy_value(&v);

src/vm/ini/free.c

@@ -1,14 +1,34 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-11-30
  */
 
+/**
+ * @file free.c
+ * @brief VM opcode snippet for releasing an INI handle (OP_INI_FREE).
+ *
+ * This file is included into the main VM dispatch switch in vm.c. It is only
+ * compiled when FUN_WITH_INI is enabled and iniparser headers are available.
+ *
+ * Opcode: OP_INI_FREE
+ * Stack: [handle:int] -> [ok:int]
+ *
+ * Behavior
+ * - Pops an integer handle referring to an INI dictionary previously returned
+ *   by OP_INI_LOAD.
+ * - Attempts to close the underlying dictionary and free the registry slot.
+ * - Pushes 1 on success, 0 if the handle was invalid or already freed.
+ *
+ * Errors
+ * - No VM error is thrown for invalid handles; the opcode simply returns 0.
+ *
+ * See also
+ * - ini_alloc_handle(), ini_free_handle() in src/vm/ini/handles.c
+ */
 /* OP_INI_FREE: pops handle; pushes 1/0 */
 #ifdef FUN_WITH_INI
 case OP_INI_FREE: {

src/vm/ini/get_bool.c

@@ -1,14 +1,33 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from getters.c)
  */
 
+/**
+ * @file get_bool.c
+ * @brief VM opcode snippet for reading a boolean from an INI dictionary (OP_INI_GET_BOOL).
+ *
+ * Included by vm.c when FUN_WITH_INI is enabled.
+ *
+ * Opcode: OP_INI_GET_BOOL
+ * Stack: [default:int|bool] [key:string] [section:string] [handle:int] -> [out:int]
+ *
+ * Behavior
+ * - Pops default value (0/1), key, section, and handle.
+ * - Looks up the entry "section:key" in the referenced dictionary. If not found,
+ *   also tries a dotted variant "section.key" for compatibility.
+ * - Accepts textual booleans (true/false, yes/no, on/off; case-insensitive) and
+ *   numeric values (non-zero => true). Falls back to the provided default when
+ *   parsing fails or entry is missing.
+ * - Pushes 1 for true or 0 for false.
+ *
+ * Errors
+ * - Invalid handle or arguments simply yield the default value; no exception.
+ */
 /* OP_INI_GET_BOOL */
 #ifdef FUN_WITH_INI
 case OP_INI_GET_BOOL: {

src/vm/ini/get_double.c

@@ -1,14 +1,27 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from getters.c)
  */
 
+/**
+ * @file get_double.c
+ * @brief VM opcode snippet for reading a floating-point value from INI (OP_INI_GET_DOUBLE).
+ *
+ * Opcode: OP_INI_GET_DOUBLE
+ * Stack: [default:float|int] [key:string] [section:string] [handle:int] -> [out:float]
+ *
+ * Behavior
+ * - Pops default, key, section, and handle; looks up "section:key" (and
+ *   dotted fallback) and attempts to parse as double using strtod().
+ * - If lookup or parsing fails, pushes the provided default.
+ *
+ * Errors
+ * - Invalid handle/args simply produce the default; no exception raised.
+ */
 /* OP_INI_GET_DOUBLE */
 #ifdef FUN_WITH_INI
 case OP_INI_GET_DOUBLE: {

src/vm/ini/get_int.c

@@ -1,14 +1,27 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from getters.c)
  */
 
+/**
+ * @file get_int.c
+ * @brief VM opcode snippet for reading an integer from INI (OP_INI_GET_INT).
+ *
+ * Opcode: OP_INI_GET_INT
+ * Stack: [default:int] [key:string] [section:string] [handle:int] -> [out:int]
+ *
+ * Behavior
+ * - Pops default, key, section, and handle; looks up "section:key" (and dotted
+ *   fallback) and attempts to parse as base-10 integer using strtol().
+ * - If lookup or parsing fails, returns the provided default.
+ *
+ * Errors
+ * - Invalid handle/args produce the default; no VM exception is raised.
+ */
 /* OP_INI_GET_INT */
 #ifdef FUN_WITH_INI
 case OP_INI_GET_INT: {

src/vm/ini/get_string.c

@@ -1,14 +1,27 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from getters.c)
  */
 
+/**
+ * @file get_string.c
+ * @brief VM opcode snippet for reading a string from INI (OP_INI_GET_STRING).
+ *
+ * Opcode: OP_INI_GET_STRING
+ * Stack: [default:string] [key:string] [section:string] [handle:int] -> [out:string]
+ *
+ * Behavior
+ * - Pops default string, key, section, and handle; looks up "section:key" and
+ *   a dotted fallback. If not found, uses the provided default.
+ * - Pushes the resulting string (copied into a VM Value).
+ *
+ * Errors
+ * - Invalid handle/args result in pushing the default (or empty string).
+ */
 /* OP_INI_GET_STRING */
 #ifdef FUN_WITH_INI
 case OP_INI_GET_STRING: {

src/vm/ini/handles.c

@@ -1,4 +1,4 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
@@ -7,6 +7,15 @@
  * https://opensource.org/license/apache-2-0
  */
 
+/**
+ * @file handles.c
+ * @brief INI handle registry implementation used by VM INI opcodes.
+ *
+ * Provides a tiny fixed-size registry mapping small integer handles to
+ * iniparser dictionary pointers. Not thread-safe. Handles are positive
+ * integers in range [1, 63].
+ */
+
 #ifdef FUN_WITH_INI
 #if defined(__has_include)
 #if __has_include(<iniparser/iniparser.h>)

src/vm/ini/handles.h

@@ -5,11 +5,12 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-11-30
  */
 
-/** INI handle registry for iniparser 4.2.6 */
+/**
+ * @file handles.h
+ * @brief INI handle registry for iniparser 4.2.6 used by INI VM opcodes.
+ */
 #pragma once
 
 #ifdef FUN_WITH_INI
@@ -29,19 +30,43 @@
 #endif
 #include <stddef.h>
 
+/**
+ * @brief One slot in the global INI handle registry.
+ * @details Associates an iniparser dictionary pointer with an in-use flag.
+ */
 typedef struct {
   dictionary *dict;
   int in_use;
 } IniSlot;
 
-/* Single global registry (defined in handles.c) */
+/** Single global registry (defined in handles.c). */
 extern IniSlot g_ini[64];
 
-/* Registry API (implemented in handles.c) */
+/**
+ * @brief Allocate a registry handle for a newly created dictionary.
+ * @param d Pointer to an iniparser dictionary.
+ * @return Handle id (>0) on success or 0 on failure.
+ */
 int ini_alloc_handle(dictionary *d);
+/**
+ * @brief Look up a dictionary pointer by registry handle.
+ * @param h Handle id previously returned by ini_alloc_handle().
+ * @return Pointer to dictionary or NULL if not found.
+ */
 dictionary *ini_get(int h);
+/**
+ * @brief Free a previously allocated handle and close its dictionary.
+ * @param h Handle id to free.
+ * @return 1 on success, 0 on error (invalid handle or not in use).
+ */
 int ini_free_handle(int h);
 
-/* Helper to build section:key string safely into provided buffer (implemented in handles.c) */
+/**
+ * @brief Build a fully qualified key "section:key" into a caller-provided buffer.
+ * @param buf Destination buffer.
+ * @param cap Capacity of buf in bytes (including terminator).
+ * @param sec Section name (may be NULL for default section).
+ * @param key Key name (must not be NULL).
+ */
 void ini_make_full_key(char *buf, size_t cap, const char *sec, const char *key);
 #endif /* FUN_WITH_INI */

src/vm/ini/load.c

@@ -1,14 +1,28 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-11-30
  */
 
+/**
+ * @file load.c
+ * @brief VM opcode snippet for loading an INI file (OP_INI_LOAD).
+ *
+ * Opcode: OP_INI_LOAD
+ * Stack: [path:string] -> [handle:int]
+ *
+ * Behavior
+ * - Pops a filesystem path and attempts to parse it via iniparser_load().
+ * - On success, registers the resulting dictionary and pushes a positive
+ *   handle. On failure, pushes 0.
+ *
+ * Notes
+ * - The returned handle must later be released with OP_INI_FREE to avoid
+ *   leaking dictionary objects.
+ */
 /* OP_INI_LOAD: pops path string; pushes handle (>0) or 0 */
 #ifdef FUN_WITH_INI
 case OP_INI_LOAD: {

src/vm/ini/save.c

@@ -1,14 +1,27 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from set_unset_save.c)
  */
 
+/**
+ * @file save.c
+ * @brief VM opcode snippet for saving an INI dictionary to a file (OP_INI_SAVE).
+ *
+ * Opcode: OP_INI_SAVE
+ * Stack: [path:string] [handle:int] -> [ok:int]
+ *
+ * Behavior
+ * - Pops a path and a handle. If the handle is valid, opens the path for
+ *   writing and dumps the dictionary in INI format. Pushes 1 on success,
+ *   otherwise 0.
+ *
+ * Errors
+ * - Failing fopen() or invalid handle simply return 0; no exception is thrown.
+ */
 /* OP_INI_SAVE */
 #ifdef FUN_WITH_INI
 case OP_INI_SAVE: {

src/vm/ini/set.c

@@ -1,14 +1,28 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from set_unset_save.c)
  */
 
+/**
+ * @file set.c
+ * @brief VM opcode snippet for setting an INI value (OP_INI_SET).
+ *
+ * Opcode: OP_INI_SET
+ * Stack: [value:any] [key:string] [section:string] [handle:int] -> [ok:int]
+ *
+ * Behavior
+ * - Pops value, key, section, and handle. Converts the value to a string using
+ *   value_to_string_alloc() and stores it under "section:key" (and a dotted
+ *   fallback) via dictionary_set().
+ * - Pushes 1 on success, 0 on failure (invalid args/handle or allocation fail).
+ *
+ * Errors
+ * - No VM exception is thrown; failures return 0.
+ */
 /* OP_INI_SET */
 #ifdef FUN_WITH_INI
 case OP_INI_SET: {

src/vm/ini/stubs.c

@@ -1,6 +1,11 @@
-/*
- * This file provides stub handlers for INI opcodes when FUN_WITH_INI is disabled.
- * Each opcode reports a clear runtime error and returns a safe default.
+/**
+ * @file stubs.c
+ * @brief Stub opcode implementations for INI support when FUN_WITH_INI is disabled.
+ *
+ * These cases are compiled into the VM dispatch when the INI feature is not
+ * enabled. Each opcode prints a descriptive runtime error and pushes a safe
+ * default (0, 0.0, or empty string) to keep execution proceeding without
+ * crashing.
  */
 
 /* OP_INI_LOAD: pops path string; pushes 0 (invalid handle) */

src/vm/ini/unset.c

@@ -1,14 +1,28 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-10 (split from set_unset_save.c)
  */
 
+/**
+ * @file unset.c
+ * @brief VM opcode snippet for removing an INI entry (OP_INI_UNSET).
+ *
+ * Opcode: OP_INI_UNSET
+ * Stack: [key:string] [section:string] [handle:int] -> [ok:int]
+ *
+ * Behavior
+ * - Pops key, section, and handle. Removes both "section:key" and a dotted
+ *   fallback key from the dictionary. Pushes 1 if the operation was attempted
+ *   (with a valid handle and arguments), otherwise 0.
+ *
+ * Notes
+ * - iniparser 4.2.6 dictionary_unset() returns void; we assume success when
+ *   called with valid parameters.
+ */
 /* OP_INI_UNSET */
 #ifdef FUN_WITH_INI
 case OP_INI_UNSET: {

src/vm/io/input_line.c

@@ -1,3 +1,53 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://fun-lang.xyz/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the Apache-2.0 license.
+ * https://opensource.org/license/apache-2-0
+ */
+ 
+/**
+ * @file input_line.c
+ * @brief Implements the OP_INPUT_LINE opcode for interactive console input.
+ *
+ * This snippet handles the OP_INPUT_LINE instruction in the VM dispatch. It can
+ * optionally print a prompt (taken from the stack) and can read input in a
+ * hidden mode (terminal echo disabled) suitable for passwords.
+ *
+ * Operand bits (inst.operand):
+ * - bit0 (1): Has prompt. When set, the top of the stack is popped and
+ *             converted to string, printed without a trailing newline.
+ * - bit1 (2): Hidden input. When set, terminal echo is temporarily disabled
+ *             while reading the line (best-effort, platform dependent).
+ *
+ * Stack effects:
+ * - If bit0 is set: pop(prompt)
+ * - Always: push(result_string)
+ *
+ * Behavior:
+ * - Converts an optional prompt Value to string using value_to_string_alloc,
+ *   prints it to stdout without a newline, and flushes the stream.
+ * - If hidden is requested, disables terminal echo (POSIX termios or Win32
+ *   console modes) before reading.
+ * - Reads a single line from stdin, accepting both "\n" and "\r\n" endings.
+ * - Restores terminal echo if it was disabled and, when a prompt was printed,
+ *   emits a newline for a better UX.
+ * - Pushes the captured line as a Fun string (never NULL; empty string on
+ *   failure or EOF).
+ *
+ * Errors and corner cases:
+ * - Memory allocation failures are reported to stderr; an empty string is
+ *   pushed in such cases to keep execution flowing.
+ * - If echo toggling fails, input still proceeds with echo enabled.
+ * - EOF before any character yields an empty string.
+ *
+ * Example:
+ *   // Bytecode: [optional PUSH prompt], OP_INPUT_LINE(operand)
+ *   // operand bit0=1 (has prompt), bit1=2 (hidden) can be combined
+ *   // Stack before (bit0=1): ["Enter password: "]
+ *   // Stack after: ["user-typed-line"]
+ */
 case OP_INPUT_LINE: {
   /* operand bit flags:
    *  bit0 (1): has prompt (string or any value convertible to string) — top of stack holds prompt when set

src/vm/json/from_file.c

@@ -5,8 +5,30 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file from_file.c
+ * @brief VM opcode snippet for loading a JSON document from a file.
  *
- * Added: 2025-11-24
+ * This snippet is included by vm.c and implements the OP_JSON_FROM_FILE
+ * instruction. It expects a path on the VM stack, reads the file using
+ * json-c, converts the resulting json_object tree into a Fun Value, and
+ * pushes that Value back on the VM stack.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled (json-c
+ * available). When disabled, the opcode consumes its argument (if any)
+ * and pushes Nil.
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: path (any; converted to string)
+ * - Pushes: Value converted from JSON, or Nil on error
+ *
+ * Errors and edge cases:
+ * - If the path cannot be converted to a C string or json_object_from_file
+ *   fails (e.g., missing file, invalid JSON), the opcode pushes Nil.
+ * - The created json_object is released after conversion; ownership of the
+ *   pushed Fun Value follows normal VM semantics.
  */
 
 /* JSON_FROM_FILE */

src/vm/json/parse.c

@@ -5,8 +5,28 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file parse.c
+ * @brief VM opcode snippet for parsing a JSON string into a Fun Value.
  *
- * Added: 2025-11-24
+ * Implements the OP_JSON_PARSE instruction. Expects a string (or any value
+ * convertible to string) on the stack, parses it with json-c, converts the
+ * resulting json_object to a Fun Value and pushes it.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled. Otherwise the
+ * opcode consumes its argument and pushes Nil.
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: text (any; converted to string)
+ * - Pushes: Value converted from JSON, or Nil on error
+ *
+ * Errors and edge cases:
+ * - If allocation fails, tokenization fails, or the text is not valid JSON,
+ *   the opcode pushes Nil.
+ * - The temporary json-c objects are released after conversion; ownership of
+ *   the pushed Fun Value follows normal VM semantics.
  */
 
 /* JSON_PARSE */

src/vm/json/stringify.c

@@ -5,8 +5,27 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file stringify.c
+ * @brief VM opcode snippet for converting a Fun Value to a JSON string.
  *
- * Added: 2025-11-24
+ * Implements the OP_JSON_STRINGIFY instruction. Expects a boolean/integer flag
+ * indicating pretty-printing and a Value to serialize. Uses json-c to build a
+ * json_object from the Value and then renders it to a string, which is pushed
+ * back to the stack.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled. Otherwise the
+ * opcode consumes its two arguments and pushes the string "null".
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: pretty (bool/int), value (any)
+ * - Pushes: string (JSON representation)
+ *
+ * Errors and edge cases:
+ * - If conversion to json_object fails, an empty string is pushed.
+ * - Pretty printing selects JSON_C_TO_STRING_PRETTY; otherwise plain output.
  */
 
 /* JSON_STRINGIFY */

src/vm/json/to_file.c

@@ -5,8 +5,27 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file to_file.c
+ * @brief VM opcode snippet for writing a Fun Value as JSON to a file.
  *
- * Added: 2025-11-24
+ * Implements the OP_JSON_TO_FILE instruction. Expects a pretty-print flag,
+ * a Value to serialize, and a path. Serializes the Value via json-c and
+ * writes it to the specified file path.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled. Otherwise the
+ * opcode consumes three arguments and pushes 0 (failure).
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: pretty (bool/int), value (any), path (any; converted to string)
+ * - Pushes: int (1 on success, 0 on failure)
+ *
+ * Errors and edge cases:
+ * - If the path cannot be converted to a C string or file writing fails,
+ *   the opcode pushes 0.
+ * - Pretty printing selects JSON_C_TO_STRING_PRETTY; otherwise plain output.
  */
 
 /* JSON_TO_FILE */

src/vm/line.c

@@ -7,6 +7,18 @@
  * https://opensource.org/license/apache-2-0
  */
 
+/**
+ * @file line.c
+ * @brief Implements the OP_LINE pseudo-opcode to update the current source line.
+ *
+ * This snippet is included into the VM dispatch loop and handles the OP_LINE
+ * instruction. It records the source line number carried in the instruction's
+ * operand so that runtime errors and debugger output can reference the correct
+ * line in the original program.
+ *
+ * Stack contract: none (does not read or write the VM value stack).
+ */
+
 case OP_LINE: {
   /* operand holds the source line number */
   vm->current_line = inst.operand;

src/vm/math/ceil.c

@@ -5,13 +5,33 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**
  * @file ceil.c
  * @brief Implements the OP_CEIL opcode using C99 math.h ceil().
+ *
+ * VM opcode snippet included by vm.c. Provides numeric ceiling operation.
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float) from the stack.
+ * - Applies ceil(x) in double precision.
+ * - If the result is an exact 64-bit integer, pushes VAL_INT; otherwise VAL_FLOAT.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: ceil(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT.
+ * - Other types cause a runtime error.
+ *
+ * Errors:
+ * - Exits with an error message if the operand is not a number.
+ *
+ * Example:
+ * - Input stack: [2.1] → Output stack: [3]
+ * - Input stack: [-2.1] → Output stack: [-2]
  */
 
 #include <math.h>

src/vm/math/cos.c

@@ -5,13 +5,29 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file cos.c
  * @brief Implements the OP_COS opcode using C99 math.h cos().
+ *
+ * VM opcode snippet included by vm.c. Provides cosine function.
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float) from the stack.
+ * - Computes cos(x) in double precision.
+ * - Always pushes a VAL_FLOAT result.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: cos(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT.
+ * - Other types cause a runtime error.
+ *
+ * Example:
+ * - Input [0] → Output [1.0]
  */
 
 #include <math.h>

src/vm/math/exp.c

@@ -5,13 +5,25 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file exp.c
  * @brief Implements the OP_EXP opcode using C99 math.h exp().
+ *
+ * VM opcode snippet included by vm.c. Provides the natural exponential function.
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float).
+ * - Computes e^x in double precision.
+ * - Pushes a VAL_FLOAT result.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: exp(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; others raise a runtime error.
  */
 
 #include <math.h>

src/vm/math/floor.c

@@ -5,13 +5,33 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**
  * @file floor.c
  * @brief Implements the OP_FLOOR opcode using C99 math.h floor().
+ *
+ * VM opcode snippet included by vm.c. Provides numeric floor operation.
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float) from the stack.
+ * - Applies floor(x) in double precision.
+ * - If the result is an exact 64-bit integer, pushes VAL_INT; otherwise VAL_FLOAT.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: floor(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT.
+ * - Other types cause a runtime error.
+ *
+ * Errors:
+ * - Exits with an error message if the operand is not a number.
+ *
+ * Example:
+ * - Input stack: [2.9] → Output stack: [2]
+ * - Input stack: [-2.1] → Output stack: [-3]
  */
 
 #include <math.h>

src/vm/math/fmax.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**

src/vm/math/fmin.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**

src/vm/math/gcd.c

@@ -5,13 +5,23 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**
  * @file gcd.c
  * @brief Implements the OP_GCD opcode for greatest common divisor.
+ *
+ * Behavior:
+ * - Pops two numeric operands (a, b). Floats are truncated to int64.
+ * - Computes gcd(|a|, |b|) using Euclid's algorithm.
+ * - Pushes VAL_INT result.
+ *
+ * Stack effect:
+ * - Pop: b, a
+ * - Push: gcd(a, b)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; others cause a runtime error.
  */
 
 case OP_GCD: {

src/vm/math/isqrt.c

@@ -5,13 +5,23 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**
  * @file isqrt.c
  * @brief Implements the OP_ISQRT opcode for integer square root (floor).
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float), converts to int64.
+ * - Computes floor(sqrt(max(0, x))) as an integer without floating point.
+ * - Pushes VAL_INT result.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: isqrt(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; others cause a runtime error.
  */
 
 case OP_ISQRT: {

src/vm/math/lcm.c

@@ -5,13 +5,23 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**
  * @file lcm.c
  * @brief Implements the OP_LCM opcode for least common multiple.
+ *
+ * Behavior:
+ * - Pops two numeric operands (a, b). Floats are truncated to int64.
+ * - Computes lcm(|a|, |b|) using gcd; returns 0 if either input is 0.
+ * - Pushes VAL_INT result. May overflow silently on extreme inputs.
+ *
+ * Stack effect:
+ * - Pop: b, a
+ * - Push: lcm(a, b)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; others cause a runtime error.
  */
 
 case OP_LCM: {

src/vm/math/log.c

@@ -5,13 +5,23 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file log.c
  * @brief Implements the OP_LOG opcode using C99 math.h log() (natural logarithm).
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float).
+ * - If x <= 0, pushes NaN to indicate domain error; otherwise pushes ln(x).
+ * - Result type is VAL_FLOAT.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: ln(x) | NaN
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; errors on others.
  */
 
 #include <math.h>

src/vm/math/log10.c

@@ -5,13 +5,19 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file log10.c
  * @brief Implements the OP_LOG10 opcode using C99 math.h log10().
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float).
+ * - If x <= 0, pushes NaN; else pushes log10(x) as VAL_FLOAT.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: log10(x) | NaN
  */
 
 #include <math.h>

src/vm/math/round.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**

src/vm/math/sign.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- *  Added: 2026-01-03
  */
 
 /**

src/vm/math/sin.c

@@ -5,13 +5,28 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file sin.c
  * @brief Implements the OP_SIN opcode using C99 math.h sin().
+ *
+ * VM opcode snippet included by vm.c. Provides sine function.
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float) from the stack.
+ * - Computes sin(x) in double precision.
+ * - Always pushes a VAL_FLOAT result.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: sin(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; others cause a runtime error.
+ *
+ * Example:
+ * - Input [0] → Output [0.0]
  */
 
 #include <math.h>

src/vm/math/sqrt.c

@@ -5,13 +5,20 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file sqrt.c
  * @brief Implements the OP_SQRT opcode using C99 math.h sqrt().
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float).
+ * - If x < 0, pushes NaN; else pushes sqrt(x).
+ * - Returns VAL_INT when the result fits exactly in int64, otherwise VAL_FLOAT.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: sqrt(x) | NaN
  */
 
 #include <math.h>

src/vm/math/tan.c

@@ -5,13 +5,25 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**
  * @file tan.c
  * @brief Implements the OP_TAN opcode using C99 math.h tan().
+ *
+ * VM opcode snippet included by vm.c. Provides tangent function.
+ *
+ * Behavior:
+ * - Pops one numeric operand (int or float) from the stack.
+ * - Computes tan(x) in double precision.
+ * - Always pushes a VAL_FLOAT result.
+ *
+ * Stack effect:
+ * - Pop: x
+ * - Push: tan(x)
+ *
+ * Types:
+ * - Accepts VAL_INT and VAL_FLOAT; others cause a runtime error.
  */
 
 #include <math.h>

src/vm/math/trunc.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-01-03
  */
 
 /**

src/vm/openssl/md5.c

@@ -5,10 +5,13 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-02-19
  */
 
+ /**
+  * @file md5.c
+  * @brief VM opcode snippet: compute MD5 hash (OP_MD5). Included by vm.c.
+  */
+
 /**
  * OpenSSL MD5 builtin
  */

src/vm/openssl/ripemd160.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-02-19
  */
 
 /*

src/vm/openssl/sha256.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-02-19
  */
 
 /**

src/vm/openssl/sha512.c

@@ -5,8 +5,6 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2026-02-19
  */
 
 /**

src/vm/os/clock_mono_ms.c

@@ -5,8 +5,6 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-10-04
  */
 
 /**

src/vm/os/date_format.c

@@ -5,8 +5,6 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-10-04
  */
 
 /**

src/vm/os/env.c

@@ -7,7 +7,17 @@
  * https://opensource.org/license/apache-2-0
  */
 
-// Get environment variables of the operation system.
+/**
+ * @file env.c
+ * @brief Implements OP_ENV to read an environment variable by name.
+ *
+ * Behavior:
+ * - Pops a string key from the stack and pushes the associated environment value as string.
+ * - If the variable is not set, pushes an empty string ("") rather than Nil.
+ *
+ * Errors:
+ * - If the key is not a string, prints an error and terminates the VM with exit(1).
+ */
 
 case OP_ENV: {
   Value key = pop_value(vm);

src/vm/os/env_all.c

@@ -5,11 +5,16 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-28
  */
 
-// Get all environment variables of the operation system and push them as a map.
+/**
+ * @file env_all.c
+ * @brief Implements OP_ENV_ALL to read the full environment into a map.
+ *
+ * Behavior:
+ * - Pushes a new map where each key is an environment variable and each value is its string value.
+ * - Keys and values are copied; the caller owns the returned map Value.
+ */
 
 case OP_ENV_ALL: {
   extern char **environ;

src/vm/os/fd_poll_read.c

@@ -5,8 +5,18 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file fd_poll_read.c
+ * @brief Implements OP_FD_POLL_READ to check if a file descriptor is readable.
  *
- * Added: 2026-03-26
+ * Behavior:
+ * - Pops timeout_ms (int) and fd (int); waits up to timeout for readability; pushes 1 if readable, 0 otherwise.
+ * - On non-UNIX platforms, returns 0 (unsupported).
+ *
+ * Errors:
+ * - If types are wrong, prints an error and returns 0.
  */
 
 case OP_FD_POLL_READ: {

src/vm/os/fd_poll_write.c

@@ -5,8 +5,18 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file fd_poll_write.c
+ * @brief Implements OP_FD_POLL_WRITE to check if a file descriptor is writable.
  *
- * Added: 2026-03-26
+ * Behavior:
+ * - Pops timeout_ms (int) and fd (int); waits up to timeout for writability; pushes 1 if writable, 0 otherwise.
+ * - On non-UNIX platforms, returns 0 (unsupported).
+ *
+ * Errors:
+ * - If types are wrong, prints an error and returns 0.
  */
 
 case OP_FD_POLL_WRITE: {

src/vm/os/fd_set_nonblock.c

@@ -5,8 +5,18 @@
  * Copyright 2026 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file fd_set_nonblock.c
+ * @brief Implements OP_FD_SET_NONBLOCK to toggle O_NONBLOCK on a file descriptor.
  *
- * Added: 2026-03-26
+ * Behavior:
+ * - Pops on (int, 0/1) and fd (int); sets or clears O_NONBLOCK via fcntl; pushes 1 on success, 0 otherwise.
+ * - On non-UNIX platforms, returns 0 (unsupported).
+ *
+ * Errors:
+ * - If types are wrong, prints an error and returns 0.
  */
 
 case OP_FD_SET_NONBLOCK: {

src/vm/os/fun_version.c

@@ -5,8 +5,14 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file fun_version.c
+ * @brief VM opcode snippet: push the current Fun version string (OP_FUN_VERSION).
  *
- * Added: 2025-12-28
+ * Included into vm.c dispatch. Pushes a string constant with the build's
+ * FUN_VERSION onto the VM stack.
  */
 
 // Pushes the current Fun version string onto the stack.

src/vm/os/list_dir.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file list_dir.c
+ * @brief Implements OP_OS_LIST_DIR to list entries in a directory.
  *
- * Added: 2025-12-23
+ * Behavior:
+ * - Pops a path (string); pushes an array of file/directory names as strings.
+ * - Implementation may delegate to a platform command (e.g., ls -1) for portability.
+ *
+ * Errors:
+ * - Non-string path results in empty array; platform errors also yield an empty array.
  */
 
 case OP_OS_LIST_DIR: {

src/vm/os/proc_run.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file proc_run.c
+ * @brief Implements OP_PROC_RUN to execute a shell command and capture stdout.
  *
- * Added: 2025-10-02
+ * Behavior:
+ * - Pops command (string); runs it via the platform shell; pushes a map {"out": string, "code": int}.
+ * - "code" is the process exit status if available, otherwise -1.
+ *
+ * Errors:
+ * - On allocation failures or popen errors, returns {out: "", code: -1}.
  */
 
 #include <stdio.h>

src/vm/os/proc_system.c

@@ -5,8 +5,17 @@
  * Copyright 2025 Johannes Findeisen
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file proc_system.c
+ * @brief Implements OP_PROC_SYSTEM to execute a shell command and return exit code.
  *
- * Added: 2025-10-02
+ * Behavior:
+ * - Pops command (string); executes it using system(3); pushes the process exit code (int) or -1 on failure.
+ *
+ * Errors:
+ * - If command is not a string or cannot be executed, returns -1.
  */
 
 case OP_PROC_SYSTEM: {

src/vm/os/random_number.c

@@ -5,13 +5,20 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-12
  */
 
-/* Generate OS-based random bytes and return them hex-encoded.
- * Opcode: OP_RANDOM_NUMBER
- * Stack:  pops len (number of raw bytes), pushes hex string of length 2*len
+/**
+ * @file random_number.c
+ * @brief Implements OP_RANDOM_NUMBER to generate cryptographically secure random bytes.
+ *
+ * Behavior:
+ * - Pops len (int, number of raw bytes to generate) and pushes a lowercase hex string of length 2*len.
+ * - Uses the platform-preferred CSPRNG (e.g., getrandom/arc4random/BCryptGenRandom); falls back to /dev/urandom on UNIX.
+ * - Caps requested length to prevent excessive allocations.
+ *
+ * Errors:
+ * - If len is not an int, or negative, prints an error and pushes an empty string.
+ * - If OS RNG is unavailable or allocation fails, prints an error and terminates the VM (exit(1)).
  */
 
 #include <inttypes.h>

src/vm/os/serial_close.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file serial_close.c
+ * @brief Implements OP_SERIAL_CLOSE to close an open serial port.
  *
- * Added: 2025-12-28
+ * Behavior:
+ * - Pops fd (int); attempts to close it; pushes 1 on success, 0 on failure.
+ * - Only supported on UNIX-like systems.
+ *
+ * Errors:
+ * - If argument type is wrong, prints an error and returns 0.
  */
 
 #ifdef __unix__

src/vm/os/serial_config.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file serial_config.c
+ * @brief Implements OP_SERIAL_CONFIG to change serial port parameters.
  *
- * Added: 2025-12-28
+ * Behavior:
+ * - Pops config map and fd (int); applies selected settings (baud, parity, bits, stop) and pushes 1 on success, 0 on failure.
+ * - Only supported on UNIX-like systems.
+ *
+ * Errors:
+ * - On wrong types or OS errors, prints an error and returns 0.
  */
 
 #ifdef __unix__

src/vm/os/serial_open.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file serial_open.c
+ * @brief Implements OP_SERIAL_OPEN to open and configure a serial port.
  *
- * Added: 2025-12-28
+ * Behavior:
+ * - Pops baud_rate (int) and device path (string); opens and configures the port; pushes fd (>0) or 0 on failure.
+ * - Only available on UNIX-like systems; Windows is unsupported and returns 0.
+ *
+ * Errors:
+ * - On wrong types or OS errors, prints an error message and returns 0.
  */
 
 #ifdef __unix__

src/vm/os/serial_recv.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file serial_recv.c
+ * @brief Implements OP_SERIAL_RECV to read bytes from a serial port.
  *
- * Added: 2025-12-28
+ * Behavior:
+ * - Pops max_len (int) and fd (int); reads up to max_len bytes; pushes a string with received data (possibly empty).
+ * - Only supported on UNIX-like systems; other platforms push empty string.
+ *
+ * Errors:
+ * - On wrong types, prints an error and pushes empty string.
  */
 
 #ifdef __unix__

src/vm/os/serial_send.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file serial_send.c
+ * @brief Implements OP_SERIAL_SEND to write bytes to a serial port.
  *
- * Added: 2025-12-28
+ * Behavior:
+ * - Pops data (string) and fd (int); writes data to the serial port; pushes number of bytes written (>=0) or -1 on error.
+ * - Only supported on UNIX-like systems; other platforms push -1.
+ *
+ * Errors:
+ * - On wrong types, prints an error and pushes -1.
  */
 
 #ifdef __unix__

src/vm/os/sleep_ms.c

@@ -5,8 +5,19 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file sleep_ms.c
+ * @brief Implements OP_SLEEP_MS to suspend execution for a number of milliseconds.
  *
- * Added: 2025-09-30
+ * Behavior:
+ * - Pops an integer value ms from the stack and sleeps for that many milliseconds.
+ * - Always pushes Nil after completion to keep stack discipline for statement POPs.
+ *
+ * Errors:
+ * - If the popped value is not an integer, prints an error, frees it, and pushes Nil.
+ * - Negative durations are treated as no-op; Nil is still pushed.
  */
 
 case OP_SLEEP_MS: {

src/vm/os/socket_close.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_close.c
+ * @brief Implements OP_SOCK_CLOSE to close a socket file descriptor.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops fd (int) and closes it; pushes 1 on success, 0 on failure.
+ * - On non-UNIX platforms, always pushes 0 (unsupported).
+ *
+ * Errors:
+ * - If argument type is wrong, prints an error and pushes 0.
  */
 
 case OP_SOCK_CLOSE: {

src/vm/os/socket_recv.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_recv.c
+ * @brief Implements OP_SOCK_RECV to receive data from a socket into a string.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops max_len (int) and fd (int); attempts to read up to max_len bytes; pushes a string with the bytes read.
+ * - On EOF or error, pushes empty string. Non-UNIX platforms return empty string (unsupported).
+ *
+ * Errors:
+ * - If argument types are wrong, prints an error and pushes empty string.
  */
 
 case OP_SOCK_RECV: {

src/vm/os/socket_send.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_send.c
+ * @brief Implements OP_SOCK_SEND to transmit data over a connected socket.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops data (string) and a socket file descriptor (int) and pushes the number of bytes sent (>=0) or -1 on error.
+ * - On non-UNIX platforms, pushes -1 (unsupported) without sending.
+ *
+ * Errors:
+ * - If argument types are wrong, prints an error, frees values, and pushes -1.
  */
 
 case OP_SOCK_SEND: {

src/vm/os/socket_tcp_accept.c

@@ -5,8 +5,17 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_tcp_accept.c
+ * @brief Implements OP_SOCK_TCP_ACCEPT to accept an incoming TCP connection.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops listening socket fd (int); accepts one connection; pushes new client fd (>0) or 0.
+ *
+ * Errors:
+ * - On wrong type or OS errors, prints an error and pushes 0. Non-UNIX platforms return 0.
  */
 
 case OP_SOCK_TCP_ACCEPT: {

src/vm/os/socket_tcp_connect.c

@@ -5,8 +5,19 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_tcp_connect.c
+ * @brief Implements OP_SOCK_TCP_CONNECT to open a TCP connection.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops port (int) and host (string); attempts to connect and pushes fd (>0) on success or 0 on failure.
+ * - Name resolution is performed via getaddrinfo; first successful connect wins.
+ *
+ * Errors:
+ * - If argument types are wrong, prints an error and pushes 0.
+ * - On non-UNIX platforms, returns 0 (unsupported).
  */
 
 case OP_SOCK_TCP_CONNECT: {

src/vm/os/socket_tcp_listen.c

@@ -5,8 +5,17 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_tcp_listen.c
+ * @brief Implements OP_SOCK_TCP_LISTEN to create a TCP listening socket.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops port (int); creates a listening socket bound to INADDR_ANY; pushes fd (>0) on success or 0.
+ *
+ * Errors:
+ * - On wrong type or OS errors, prints an error and pushes 0. Non-UNIX platforms return 0.
  */
 
 case OP_SOCK_TCP_LISTEN: {

src/vm/os/socket_unix_connect.c

@@ -5,8 +5,17 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_unix_connect.c
+ * @brief Implements OP_SOCK_UNIX_CONNECT to connect to a UNIX domain socket path.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops path (string); creates an AF_UNIX SOCK_STREAM and connects to it; pushes fd (>0) or 0.
+ *
+ * Errors:
+ * - On wrong type or OS errors, prints an error and pushes 0. Non-UNIX platforms return 0.
  */
 
 #include <string.h>

src/vm/os/socket_unix_listen.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file socket_unix_listen.c
+ * @brief Implements OP_SOCK_UNIX_LISTEN to create a UNIX domain listening socket.
  *
- * Added: 2025-10-04
+ * Behavior:
+ * - Pops path (string); creates/binds/listens on AF_UNIX socket; pushes fd (>0) or 0 on failure.
+ * - The path may be unlinked before bind to avoid EADDRINUSE.
+ *
+ * Errors:
+ * - On wrong type or OS errors, prints an error and pushes 0. Non-UNIX platforms return 0.
  */
 
 case OP_SOCK_UNIX_LISTEN: {

src/vm/os/thread_common.c

@@ -5,8 +5,20 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file thread_common.c
+ * @brief Cross-platform thread helpers and registry used by OP_THREAD_SPAWN/OP_THREAD_JOIN.
  *
- * Added: 2025-09-30
+ * This file provides a tiny cross-platform threading layer (Windows/UNIX) embedded into the
+ * VM translation unit. It exposes utilities used by VM opcodes to spawn a function call in a
+ * background thread and later join it to retrieve the result.
+ *
+ * Notes:
+ * - Thread registry is bounded by FUN_MAX_THREADS; not intended for high concurrency.
+ * - Each task owns its argument Values and transfers ownership of the result to the caller
+ *   on successful join.
  */
 
 /* Cross-platform minimal threading support embedded into vm.c TU */

src/vm/os/thread_join.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file thread_join.c
+ * @brief Implements OP_THREAD_JOIN to wait for a spawned thread and get its result.
  *
- * Added: 2025-09-30
+ * Behavior:
+ * - Pops thread id (int); waits for the thread to finish; pushes the result Value produced by the thread.
+ * - If the thread failed or id is invalid, pushes Nil.
+ *
+ * Errors:
+ * - If argument type is wrong, prints an error and pushes Nil.
  */
 
 case OP_THREAD_JOIN: {

src/vm/os/thread_spawn.c

@@ -5,8 +5,18 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file thread_spawn.c
+ * @brief Implements OP_THREAD_SPAWN to run a function in a background thread.
  *
- * Added: 2025-09-30
+ * Behavior:
+ * - Pops function and optionally one argument or an array of arguments (controlled by operand).
+ * - Spawns a new thread that invokes the function; pushes a thread id (int) or 0 on failure.
+ *
+ * Errors:
+ * - If types are wrong or spawning fails, returns 0.
  */
 
 case OP_THREAD_SPAWN: {

src/vm/os/time_now_ms.c

@@ -5,8 +5,6 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-10-04
  */
 
 /**

src/vm/pcre2/findall.c

@@ -5,8 +5,40 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file findall.c
+ * @brief Implements the OP_PCRE2_FINDALL opcode (conditional build).
  *
- * Added: 2025-11-25
+ * Finds all non-overlapping matches of a PCRE2 pattern in a subject string
+ * and returns an array of maps describing each match when FUN_WITH_PCRE2 is
+ * enabled. When PCRE2 support is disabled at build time, the opcode falls
+ * back to returning an empty array.
+ */
+
+/**
+ * OP_PCRE2_FINDALL: (pattern:any, text:any, flags:int|bool=0) -> array(map)
+ *
+ * Behavior when FUN_WITH_PCRE2 is enabled:
+ * - Pops three arguments from the VM stack: pattern, text, flags.
+ *   - pattern and text are converted to strings using value_to_string_alloc().
+ *   - flags bits map to PCRE2 options:
+ *     - 1 = PCRE2_CASELESS (I)
+ *     - 2 = PCRE2_MULTILINE (M)
+ *     - 4 = PCRE2_DOTALL (S)
+ *     - 8 = PCRE2_UTF (U)
+ *     - 16 = PCRE2_EXTENDED (X)
+ * - Compiles the pattern and scans the subject for all non-overlapping
+ *   matches. For each match, pushes into the result array a map with keys:
+ *   - "full": matched substring (group 0)
+ *   - "start": start index (int)
+ *   - "end": end index (int, exclusive)
+ *   - "groups": array of captured group strings (excluding group 0)
+ * - On compilation error or allocation failure, returns an empty array.
+ *
+ * Behavior when FUN_WITH_PCRE2 is disabled:
+ * - Pops three values and returns an empty array.
  */
 
 /* PCRE2_FINDALL */

src/vm/pcre2/match.c

@@ -5,8 +5,38 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file match.c
+ * @brief Implements the OP_PCRE2_MATCH opcode (conditional build).
  *
- * Added: 2025-11-25
+ * Executes a single PCRE2 pattern match against a subject string and returns
+ * a map describing the first match and its capture groups when FUN_WITH_PCRE2
+ * is enabled. Returns Nil when there is no match or on error. When PCRE2
+ * support is disabled at build time, the opcode always returns Nil.
+ */
+
+/**
+ * OP_PCRE2_MATCH: (pattern:any, text:any, flags:int|bool=0) -> map|Nil
+ *
+ * Behavior when FUN_WITH_PCRE2 is enabled:
+ * - Pops: pattern, text, flags. Converts pattern/text to strings.
+ * - Flags bits:
+ *   - 1 = PCRE2_CASELESS (I)
+ *   - 2 = PCRE2_MULTILINE (M)
+ *   - 4 = PCRE2_DOTALL (S)
+ *   - 8 = PCRE2_UTF (U)
+ *   - 16 = PCRE2_EXTENDED (X)
+ * - On successful match, returns a map with keys:
+ *   - "full": matched substring (group 0)
+ *   - "start": start index (int)
+ *   - "end": end index (int, exclusive)
+ *   - "groups": array of captured group strings (excluding group 0)
+ * - On no match or compile error, returns Nil.
+ *
+ * Behavior when FUN_WITH_PCRE2 is disabled:
+ * - Pops three values and returns Nil.
  */
 
 /* PCRE2_MATCH */

src/vm/pcre2/test.c

@@ -9,6 +9,33 @@
  * Added: 2025-11-25
  */
 
+/**
+ * @file test.c
+ * @brief Implements the OP_PCRE2_TEST opcode (conditional build).
+ *
+ * Tests whether a PCRE2 pattern matches a subject string and returns 1 on
+ * success or 0 otherwise when FUN_WITH_PCRE2 is enabled. When PCRE2 support
+ * is disabled at build time, the opcode always returns 0.
+ */
+
+/**
+ * OP_PCRE2_TEST: (pattern:any, text:any, flags:int|bool=0) -> int
+ *
+ * Behavior when FUN_WITH_PCRE2 is enabled:
+ * - Pops: pattern, text, flags. Converts pattern/text to strings.
+ * - Flags bits:
+ *   - 1 = PCRE2_CASELESS (I)
+ *   - 2 = PCRE2_MULTILINE (M)
+ *   - 4 = PCRE2_DOTALL (S)
+ *   - 8 = PCRE2_UTF (U)
+ *   - 16 = PCRE2_EXTENDED (X)
+ * - Returns 1 if pcre2_match() returns a non-negative result, else 0.
+ * - On compile error or allocation failure, returns 0.
+ *
+ * Behavior when FUN_WITH_PCRE2 is disabled:
+ * - Pops three values and returns 0.
+ */
+
 /* PCRE2_TEST */
 case OP_PCRE2_TEST: {
 #ifdef FUN_WITH_PCRE2

src/vm/pcsc/connect.c

@@ -5,8 +5,24 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file connect.c
+ * @brief Implements the OP_PCSC_CONNECT opcode (conditional build).
  *
- * Added: 2025-10-02
+ * Connects to a smart card in the specified reader using an existing PC/SC
+ * context. On success, allocates/returns a card handle id from the internal
+ * registry. When PCSC support is disabled at build time, this opcode returns 0.
+ */
+
+/**
+ * OP_PCSC_CONNECT: (ctx_id:int, reader_name:any) -> int
+ *
+ * - Pops: reader_name (converted to string), then ctx_id.
+ * - Pushes: card handle id (>0) on success; 0 on error/invalid inputs or when
+ *   FUN_WITH_PCSC is disabled.
+ * - Notes: Uses SCARD_SHARE_SHARED and negotiates T0/T1 protocols.
  */
 
 /* PCSC connect */

src/vm/pcsc/disconnect.c

@@ -5,8 +5,23 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file disconnect.c
+ * @brief Implements the OP_PCSC_DISCONNECT opcode (conditional build).
  *
- * Added: 2025-10-02
+ * Disconnects a previously connected smart-card handle and frees the
+ * corresponding registry slot. When PCSC support is disabled at build time,
+ * this opcode returns 0 after consuming its argument.
+ */
+
+/**
+ * OP_PCSC_DISCONNECT: (handle_id:int) -> int
+ *
+ * - Pops: handle_id.
+ * - Pushes: 1 on success; 0 on error (invalid id/not found) or when disabled.
+ * - Notes: Uses SCardDisconnect(..., SCARD_LEAVE_CARD).
  */
 
 /* PCSC disconnect */

src/vm/pcsc/establish.c

@@ -5,8 +5,22 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file establish.c
+ * @brief Implements the OP_PCSC_ESTABLISH opcode (conditional build).
  *
- * Added: 2025-10-02
+ * Creates a new PC/SC context using SCardEstablishContext(SCARD_SCOPE_SYSTEM)
+ * and registers it in the internal PCSC context registry when FUN_WITH_PCSC
+ * is enabled. Returns the allocated context id on success, or 0 on failure.
+ * When PCSC support is disabled at build time, this opcode returns 0.
+ */
+
+/**
+ * OP_PCSC_ESTABLISH: () -> int
+ *
+ * - Returns: context id (>0) on success; 0 on error or when disabled.
  */
 
 /* PCSC establish */

src/vm/pcsc/list_readers.c

@@ -5,8 +5,22 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file list_readers.c
+ * @brief Implements the OP_PCSC_LIST_READERS opcode (conditional build).
  *
- * Added: 2025-10-02
+ * Lists available PC/SC reader names for a given context. On success returns
+ * an array of strings. When PCSC support is disabled at build time, returns an
+ * empty array after consuming its argument to keep the stack balanced.
+ */
+
+/**
+ * OP_PCSC_LIST_READERS: (ctx_id:int) -> array<string>
+ *
+ * - Pops: ctx_id.
+ * - Pushes: array of reader names on success; empty array on error/disabled.
  */
 
 /* PCSC list_readers */