Doxygen code comment cleanups and fixes. No code changes. (0.41.5)

.gitignore

@@ -11,7 +11,9 @@ build/*
 build_debug/*
 build_release/*
 cmake_install.cmake
+compile_commands.json
 database.sqlite
+defines.txt
 demo_*
 dist/
 downloaded.png

src/bytecode.h

@@ -15,7 +15,7 @@
  * instruction representation (@ref Instruction), and the owning bytecode
  * container (@ref Bytecode) together with minimal constructor/manipulation
  * helpers. The concrete execution semantics for each opcode are implemented
- * in the VM (see vm.c and vm/* handlers).
+ * in the VM (see vm.c and vm/some_file.c handlers).
  */
 #ifndef FUN_BYTECODE_H
 #define FUN_BYTECODE_H

src/parser.c

@@ -38,9 +38,6 @@
  *     vm_run(&vm, bc);
  *     bytecode_free(bc);
  * }
- *
- * @author Johannes Findeisen
- * @date 2025-09-16
  */
 
 #include "parser.h"

src/parser_utils.c

@@ -82,7 +82,7 @@ static void skip_line(const char *src, size_t len, size_t *pos) {
 }
 
 /**
- * @brief Skip whitespace, then line (//) and block (/* ... */) comments.
+ * @brief Skip whitespace, then line and block comments.
  * Continues until the next non-comment, non-whitespace character.
  */
 static void skip_comments(const char *src, size_t len, size_t *pos) {

src/vm/arithmetic/add.c

@@ -27,9 +27,9 @@
  * - Exits with an error if memory allocation fails during string concatenation.
  *
  * Example:
- * // Bytecode: OP_ADD
+ * - Bytecode: OP_ADD
- * // Stack before: [2, 3]
+ * - Stack before: [2, 3]
- * // Stack after: [5]
+ * - Stack after: [5]
  */
 
 case OP_ADD: {

src/vm/arithmetic/div.c

@@ -26,11 +26,11 @@
  * - Raises a runtime error on division by zero (both integer and floating cases).
  *
  * Example:
- * // Bytecode: OP_DIV
+ * - Bytecode: OP_DIV
- * // Stack before: [10, 2]
+ * - Stack before: [10, 2]
- * // Stack after: [5]
+ * - Stack after: [5]
- * // Stack before: [5.0, 2]
+ * - Stack before: [5.0, 2]
- * // Stack after: [2.5]
+ * - Stack after: [2.5]
  */
 
 case OP_DIV: {

src/vm/arithmetic/mul.c

@@ -25,11 +25,11 @@
  * - Raises a runtime error and aborts execution if operands are not numeric.
  *
  * Example:
- * // Bytecode: OP_MUL
+ * - Bytecode: OP_MUL
- * // Stack before: [3, 4]
+ * - Stack before: [3, 4]
- * // Stack after: [12]
+ * - Stack after: [12]
- * // Stack before: [2.5, 4]
+ * - Stack before: [2.5, 4]
- * // Stack after: [10.0]
+ * - Stack after: [10.0]
  */
 
 case OP_MUL: {

src/vm/arithmetic/sub.c

@@ -25,11 +25,11 @@
  * - Raises a runtime error and aborts execution if operands are not numeric.
  *
  * Example:
- * // Bytecode: OP_SUB
+ * - Bytecode: OP_SUB
- * // Stack before: [10, 4]
+ * - Stack before: [10, 4]
- * // Stack after: [6]
+ * - Stack after: [6]
- * // Stack before: [10.0, 3]
+ * - Stack before: [10.0, 3]
- * // Stack after: [7.0]
+ * - Stack after: [7.0]
  */
 
 case OP_SUB: {

src/vm/arrays/apop.c

@@ -24,9 +24,9 @@
  * - Exits with an error if the array is empty.
  *
  * Example:
- * // Bytecode: OP_APOP
+ * - Bytecode: OP_APOP
- * // Stack before: [[10, 20, 30]]
+ * - Stack before: [[10, 20, 30]]
- * // Stack after: [30]
+ * - Stack after: [30]
  */
 
 case OP_APOP: {

src/vm/arrays/clear.c

@@ -24,9 +24,9 @@
  * - Exits with a runtime error if the operand is not an array.
 
  * Example:
- * // Bytecode: OP_CLEAR
+ * - Bytecode: OP_CLEAR
- * // Stack before: [[10, 20, 30]]
+ * - Stack before: [[10, 20, 30]]
- * // Stack after: [0]
+ * - Stack after: [0]
  */
 
 case OP_CLEAR: {

src/vm/arrays/contains.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the array is of the wrong type.
  *
  * Example:
- * // Bytecode: OP_CONTAINS
+ * - Bytecode: OP_CONTAINS
- * // Stack before: [20, [10, 20, 30]]
+ * - Stack before: [20, [10, 20, 30]]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_CONTAINS: {

src/vm/arrays/enumerate.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the array is of the wrong type.
  *
  * Example:
- * // Bytecode: OP_ENUMERATE
+ * - Bytecode: OP_ENUMERATE
- * // Stack before: [[10, 20, 30]]
+ * - Stack before: [[10, 20, 30]]
- * // Stack after: [[[0, 10], [1, 20], [2, 30]]]
+ * - Stack after: [[[0, 10], [1, 20], [2, 30]]]
  */
 
 case OP_ENUMERATE: {

src/vm/arrays/index_get.c

@@ -25,9 +25,9 @@
  *   is of the wrong type, or if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_INDEX_GET
+ * - Bytecode: OP_INDEX_GET
- * // Stack before: [1, [10, 20, 30]]
+ * - Stack before: [1, [10, 20, 30]]
- * // Stack after: [20]
+ * - Stack after: [20]
  */
 
 case OP_INDEX_GET: {

src/vm/arrays/index_of.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the array is of the wrong type.
  *
  * Example:
- * // Bytecode: OP_INDEX_OF
+ * - Bytecode: OP_INDEX_OF
- * // Stack before: [20, [10, 20, 30]]
+ * - Stack before: [20, [10, 20, 30]]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_INDEX_OF: {

src/vm/arrays/index_set.c

@@ -24,9 +24,9 @@
  *   is of the wrong type, or if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_INDEX_SET
+ * - Bytecode: OP_INDEX_SET
- * // Stack before: [42, 1, [10, 20, 30]]
+ * - Stack before: [42, 1, [10, 20, 30]]
- * // Stack after: [[10, 42, 30]]
+ * - Stack after: [[10, 42, 30]]
  */
 
 case OP_INDEX_SET: {

src/vm/arrays/insert.c

@@ -25,9 +25,9 @@
  * - Exits with an error if memory allocation fails during the insertion.
  *
  * Example:
- * // Bytecode: OP_INSERT
+ * - Bytecode: OP_INSERT
- * // Stack before: [42, 1, [10, 20, 30]]
+ * - Stack before: [42, 1, [10, 20, 30]]
- * // Stack after: [4]
+ * - Stack after: [4]
  */
 
 case OP_INSERT: {

src/vm/arrays/join.c

@@ -24,9 +24,9 @@
  * - Exits with an error if the array or separator is of the wrong type.
  *
  * Example:
- * // Bytecode: OP_JOIN
+ * - Bytecode: OP_JOIN
- * // Stack before: [", ", ["a", "b", "c"]]
+ * - Stack before: [", ", ["a", "b", "c"]]
- * // Stack after: ["a, b, c"]
+ * - Stack after: ["a, b, c"]
  */
 
 case OP_JOIN: {

src/vm/arrays/make_array.c

@@ -24,9 +24,9 @@
  * - Exits with an error if `n` is invalid or if memory allocation fails.
  *
  * Example:
- * // Bytecode: OP_MAKE_ARRAY 3
+ * - Bytecode: OP_MAKE_ARRAY 3
- * // Stack before: [1, 2, 3]
+ * - Stack before: [1, 2, 3]
- * // Stack after: [[1, 2, 3]]
+ * - Stack after: [[1, 2, 3]]
  */
 
 case OP_MAKE_ARRAY: {

src/vm/arrays/push.c

@@ -25,9 +25,9 @@
  * - Exits with a runtime error if memory allocation fails.
  *
  * Example:
- * // Bytecode: OP_PUSH
+ * - Bytecode: OP_PUSH
- * // Stack before: [42, [10, 20, 30]]
+ * - Stack before: [42, [10, 20, 30]]
- * // Stack after: [4]
+ * - Stack after: [4]
  */
 
 case OP_PUSH: {

src/vm/arrays/remove.c

@@ -25,9 +25,9 @@
  * - Exits with a runtime error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_REMOVE
+ * - Bytecode: OP_REMOVE
- * // Stack before: [1, [10, 20, 30]]
+ * - Stack before: [1, [10, 20, 30]]
- * // Stack after: [20]
+ * - Stack after: [20]
  */
 
 case OP_REMOVE: {

src/vm/arrays/set.c

@@ -25,9 +25,9 @@
  * - Exits with a runtime error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_SET
+ * - Bytecode: OP_SET
- * // Stack before: [42, 1, [10, 20, 30]]
+ * - Stack before: [42, 1, [10, 20, 30]]
- * // Stack after: [42]
+ * - Stack after: [42]
  */
 
 case OP_SET: {

src/vm/arrays/slice.c

@@ -24,9 +24,9 @@
  * - Handles negative indices and out-of-bounds cases gracefully
  *
  * Example:
- * // Bytecode: OP_SLICE
+ * - Bytecode: OP_SLICE
- * // Stack before: [3, 1, [10,20,30,40]]
+ * - Stack before: [3, 1, [10,20,30,40]]
- * // Stack after: [[20,30]]
+ * - Stack after: [[20,30]]
  */
 
 case OP_SLICE: {

src/vm/arrays/zip.c

@@ -24,9 +24,9 @@
  * - Exits with error if arguments aren't arrays
  *
  * Example:
- * // Bytecode: OP_ZIP
+ * - Bytecode: OP_ZIP
- * // Stack before: [[1,2], ['a','b']]
+ * - Stack before: [[1,2], ['a','b']]
- * // Stack after: [[[1,'a'], [2,'b']]]
+ * - Stack after: [[[1,'a'], [2,'b']]]
  */
 
 case OP_ZIP: {

src/vm/core/dup.c

@@ -22,9 +22,9 @@
  * - Exits with an error if the stack is empty.
  *
  * Example:
- * // Bytecode: OP_DUP
+ * - Bytecode: OP_DUP
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: [42, 42]
+ * - Stack after: [42, 42]
  */
 
 case OP_DUP: {

src/vm/core/halt.c

@@ -18,9 +18,9 @@
  * - Stops the VM execution immediately.
  *
  * Example:
- * // Bytecode: OP_HALT
+ * - Bytecode: OP_HALT
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: [42]
+ * - Stack after: [42]
  */
 
 case OP_HALT:

src/vm/core/load_global.c

@@ -22,9 +22,9 @@
  * - Exits with an error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_LOAD_GLOBAL 0
+ * - Bytecode: OP_LOAD_GLOBAL 0
- * // Stack before: []
+ * - Stack before: []
- * // Stack after: [global_value]
+ * - Stack after: [global_value]
  */
 
 case OP_LOAD_GLOBAL: {

src/vm/core/load_local.c

@@ -22,9 +22,9 @@
  * - Exits with an error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_LOAD_LOCAL 0
+ * - Bytecode: OP_LOAD_LOCAL 0
- * // Stack before: []
+ * - Stack before: []
- * // Stack after: [local_value]
+ * - Stack after: [local_value]
  */
 
 case OP_LOAD_LOCAL: {

src/vm/core/nop.c

@@ -18,9 +18,9 @@
  * - Does nothing.
  *
  * Example:
- * // Bytecode: OP_NOP
+ * - Bytecode: OP_NOP
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: [42]
+ * - Stack after: [42]
  */
 
 case OP_NOP:

src/vm/core/pop.c

@@ -20,9 +20,9 @@
  * - Exits with an error if the stack is empty.
  *
  * Example:
- * // Bytecode: OP_POP
+ * - Bytecode: OP_POP
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: []
+ * - Stack after: []
  */
 
 case OP_POP: {

src/vm/core/return.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the frame stack is empty.
  *
  * Example:
- * // Bytecode: OP_RETURN
+ * - Bytecode: OP_RETURN
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: [42]
+ * - Stack after: [42]
  */
 
 case OP_RETURN: {

src/vm/core/store_global.c

@@ -22,9 +22,9 @@
  * - Exits with an error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_STORE_GLOBAL 0
+ * - Bytecode: OP_STORE_GLOBAL 0
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: []
+ * - Stack after: []
  */
 
 case OP_STORE_GLOBAL: {

src/vm/core/store_local.c

@@ -22,9 +22,9 @@
  * - Exits with an error if the index is out of bounds.
  *
  * Example:
- * // Bytecode: OP_STORE_LOCAL 0
+ * - Bytecode: OP_STORE_LOCAL 0
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: []
+ * - Stack after: []
  */
 
 case OP_STORE_LOCAL: {

src/vm/echo.c

@@ -21,8 +21,6 @@
  * - 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/io/input_line.c

@@ -43,10 +43,10 @@
  * - EOF before any character yields an empty string.
  *
  * Example:
- *   // Bytecode: [optional PUSH prompt], OP_INPUT_LINE(operand)
+ *   - Bytecode: [optional PUSH prompt], OP_INPUT_LINE(operand)
- *   // operand bit0=1 (has prompt), bit1=2 (hidden) can be combined
+ *   - operand bit0=1 (has prompt), bit1=2 (hidden) can be combined
- *   // Stack before (bit0=1): ["Enter password: "]
+ *   - Stack before (bit0=1): ["Enter password: "]
- *   // Stack after: ["user-typed-line"]
+ *   - Stack after: ["user-typed-line"]
  */
 
 case OP_INPUT_LINE: {

src/vm/io/read_file.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the file path is invalid or the file cannot be read.
  *
  * Example:
- * // Bytecode: OP_READ_FILE
+ * - Bytecode: OP_READ_FILE
- * // Stack before: ["file.txt"]
+ * - Stack before: ["file.txt"]
- * // Stack after: ["file contents"]
+ * - Stack after: ["file contents"]
  */
 
 case OP_READ_FILE: {

src/vm/io/write_file.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the file path is invalid or the file cannot be written.
  *
  * Example:
- * // Bytecode: OP_WRITE_FILE
+ * - Bytecode: OP_WRITE_FILE
- * // Stack before: ["file.txt", "data"]
+ * - Stack before: ["file.txt", "data"]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_WRITE_FILE: {

src/vm/len.c

@@ -23,12 +23,9 @@
  * - Exits with an error if the operand is not an array or string.
  *
  * Example:
- * // Bytecode: OP_LEN
+ * - Bytecode: OP_LEN
- * // Stack before: ["hello"]
+ * - Stack before: ["hello"]
- * // Stack after: [5]
+ * - Stack after: [5]
- *
- * @author Johannes Findeisen
- * @date 2025-09-16
  */
 
 case OP_LEN: {

src/vm/logic/and.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are not boolean values.
  *
  * Example:
- * // Bytecode: OP_AND
+ * - Bytecode: OP_AND
- * // Stack before: [1, 0]
+ * - Stack before: [1, 0]
- * // Stack after: [0]
+ * - Stack after: [0]
  */
 
 case OP_AND: {

src/vm/logic/eq.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are of incompatible types.
  *
  * Example:
- * // Bytecode: OP_EQ
+ * - Bytecode: OP_EQ
- * // Stack before: [42, 42]
+ * - Stack before: [42, 42]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_EQ: {

src/vm/logic/gt.c

@@ -23,10 +23,9 @@
  * - Exits with an error if the operands are of incompatible types.
  *
  * Example:
- * ```c
+ * - Bytecode: OP_GT
- * // Bytecode: OP_GT
+ * - Stack before: [42, 10]
- * // Stack before: [42, 10]
+ * - Stack after: [1]
- * // Stack after: [1]
  */
 
 case OP_GT: {

src/vm/logic/gte.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are of incompatible types.
  *
  * Example:
- * // Bytecode: OP_GTE
+ * - Bytecode: OP_GTE
- * // Stack before: [42, 42]
+ * - Stack before: [42, 42]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_GTE: {

src/vm/logic/lt.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are of incompatible types.
  *
  * Example:
- * // Bytecode: OP_LT
+ * - Bytecode: OP_LT
- * // Stack before: [10, 42]
+ * - Stack before: [10, 42]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_LT: {

src/vm/logic/lte.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are of incompatible types.
  *
  * Example:
- * // Bytecode: OP_LTE
+ * - Bytecode: OP_LTE
- * // Stack before: [42, 42]
+ * - Stack before: [42, 42]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_LTE: {

src/vm/logic/neq.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are of incompatible types.
  *
  * Example:
- * // Bytecode: OP_NEQ
+ * - Bytecode: OP_NEQ
- * // Stack before: [42, 10]
+ * - Stack before: [42, 10]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_NEQ: {

src/vm/logic/not.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operand is not a boolean value.
  *
  * Example:
- * // Bytecode: OP_NOT
+ * - Bytecode: OP_NOT
- * // Stack before: [0]
+ * - Stack before: [0]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_NOT: {

src/vm/logic/or.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are not boolean values.
  *
  * Example:
- * // Bytecode: OP_OR
+ * - Bytecode: OP_OR
- * // Stack before: [1, 0]
+ * - Stack before: [1, 0]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_OR: {

src/vm/maps/keys.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the map is of the wrong type.
  *
  * Example:
- * // Bytecode: OP_KEYS
+ * - Bytecode: OP_KEYS
- * // Stack before: [{"a": 1, "b": 2}]
+ * - Stack before: [{"a": 1, "b": 2}]
- * // Stack after: [["a", "b"]]
+ * - Stack after: [["a", "b"]]
  */
 
 case OP_KEYS: {

src/vm/maps/make_map.c

@@ -25,9 +25,9 @@
  *   or if map construction fails.
  *
  * Example:
- * // Bytecode: OP_MAKE_MAP 2
+ * - Bytecode: OP_MAKE_MAP 2
- * // Stack before: ["key1", 1, "key2", 2]
+ * - Stack before: ["key1", 1, "key2", 2]
- * // Stack after: [{"key1": 1, "key2": 2}]
+ * - Stack after: [{"key1": 1, "key2": 2}]
  */
 
 case OP_MAKE_MAP: {

src/vm/maps/values.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the map is of the wrong type.
  *
  * Example:
- * // Bytecode: OP_VALUES
+ * - Bytecode: OP_VALUES
- * // Stack before: [{"a": 1, "b": 2}]
+ * - Stack before: [{"a": 1, "b": 2}]
- * // Stack after: [[1, 2]]
+ * - Stack after: [[1, 2]]
  */
 
 case OP_VALUES: {

src/vm/math/abs.c

@@ -20,9 +20,6 @@
  *
  * Error Handling:
  * - Exits if not integer
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_ABS: {

src/vm/math/clamp.c

@@ -21,9 +21,6 @@
  * Error Handling:
  * - Exits if arguments wrong types
  * - Handles hi < lo case
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_CLAMP: {

src/vm/math/max.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are not integers.
  *
  * Example:
- * // Bytecode: OP_MAX
+ * - Bytecode: OP_MAX
- * // Stack before: [10, 42]
+ * - Stack before: [10, 42]
- * // Stack after: [42]
+ * - Stack after: [42]
  */
 
 case OP_MAX: {

src/vm/math/min.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are not integers.
  *
  * Example:
- * // Bytecode: OP_MIN
+ * - Bytecode: OP_MIN
- * // Stack before: [10, 42]
+ * - Stack before: [10, 42]
- * // Stack after: [10]
+ * - Stack after: [10]
  */
 
 case OP_MIN: {

src/vm/math/mod.c

@@ -24,9 +24,9 @@
  * - Exits with an error if the second operand is zero.
  *
  * Example:
- * // Bytecode: OP_MOD
+ * - Bytecode: OP_MOD
- * // Stack before: [10, 3]
+ * - Stack before: [10, 3]
- * // Stack after: [1]
+ * - Stack after: [1]
  */
 
 case OP_MOD: {

src/vm/math/pow.c

@@ -23,9 +23,9 @@
  * - Exits with an error if the operands are not integers.
  *
  * Example:
- * // Bytecode: OP_POW
+ * - Bytecode: OP_POW
- * // Stack before: [2, 3]
+ * - Stack before: [2, 3]
- * // Stack after: [8]
+ * - Stack after: [8]
  */
 
 case OP_POW: {

src/vm/math/random_int.c

@@ -25,9 +25,9 @@
  * - Exits with an error if the lower bound is greater than the upper bound.
  *
  * Example:
- * // Bytecode: OP_RANDOM_INT
+ * - Bytecode: OP_RANDOM_INT
- * // Stack before: [10, 1]
+ * - Stack before: [10, 1]
- * // Stack after: [7]
+ * - Stack after: [7]
  */
 
 case OP_RANDOM_INT: {

src/vm/math/random_seed.c

@@ -22,9 +22,9 @@
  * - Exits with an error if the seed is not an integer.
  *
  * Example:
- * // Bytecode: OP_RANDOM_SEED
+ * - Bytecode: OP_RANDOM_SEED
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: []
+ * - Stack after: []
  */
 
 case OP_RANDOM_SEED: {

src/vm/os/clock_mono_ms.c

@@ -11,8 +11,10 @@
  * @file clock_mono_ms.c
  * @brief Implements OP_CLOCK_MONO_MS to push monotonic clock in ms.
  *
- * Stack before: []
+ * Example:
- * Stack after: [int ms]
+ * - OP_CLOCK_MONO_MS
+ * - Stack before: []
+ * - Stack after: [int ms]
  */
 
 #include <stdint.h>

src/vm/pcsc/connect.c

@@ -14,9 +14,7 @@
  * 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.

src/vm/pcsc/disconnect.c

@@ -14,9 +14,7 @@
  * 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.
@@ -24,6 +22,10 @@
  * - Notes: Uses SCardDisconnect(..., SCARD_LEAVE_CARD).
  */
 
+/**
+
+ */
+
 /* PCSC disconnect */
 case OP_PCSC_DISCONNECT: {
 #ifdef FUN_WITH_PCSC

src/vm/pcsc/establish.c

@@ -15,9 +15,7 @@
  * 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.

src/vm/pcsc/list_readers.c

@@ -14,9 +14,7 @@
  * 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.

src/vm/pcsc/release.c

@@ -14,9 +14,7 @@
  * Releases a previously established PC/SC context and frees its registry slot.
  * When PCSC support is disabled at build time, this opcode returns 0 after
  * consuming its argument.
- */
+ * 
-
-/**
  * OP_PCSC_RELEASE: (ctx_id:int) -> int
  *
  * - Pops: ctx_id.

src/vm/pcsc/transmit.c

@@ -15,9 +15,7 @@
  * handle. Returns a map with the response bytes and status words. When PCSC
  * support is disabled at build time, consumes its arguments and returns a map
  * with code = -2.
- */
+ * 
-
-/**
  * OP_PCSC_TRANSMIT: (handle_id:int, apdu:array<int>) -> map
  *
  * - Pops: apdu array, then handle_id.

src/vm/print.c

@@ -19,12 +19,9 @@
  * - Prints the value to the output buffer.
  *
  * Example:
- * // Bytecode: OP_PRINT
+ * - Bytecode: OP_PRINT
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: []
+ * - Stack after: []
- *
- * @author Johannes Findeisen
- * @date 2025-09-16
  */
 
 case OP_PRINT: {

src/vm/rust/get_sp.c

@@ -14,9 +14,7 @@
  * Delegates to a Rust helper to read the VM's current stack pointer (sp).
  * When Rust support is disabled, this raises a runtime error and pushes -1 to
  * signal unavailability.
- */
+ * 
-
-/**
  * OP_RUST_GET_SP: () -> int | Nil
  *
  * Behavior (FUN_WITH_RUST=ON):
@@ -28,6 +26,7 @@
  * - Raises a runtime error indicating missing Rust support.
  * - Pushes integer -1 as a sentinel value.
  */
+
 case OP_RUST_GET_SP: {
 #ifdef FUN_WITH_RUST
   extern int fun_op_rget_sp(VM * vm);

src/vm/rust/hello.c

@@ -16,9 +16,7 @@
  * Rust and pushes it as a VAL_STRING onto the VM stack. When Rust support is
  * disabled, a runtime error is raised and Nil is pushed to keep stack
  * consistency.
- */
+ * 
-
-/**
  * OP_RUST_HELLO: () -> string | Nil
  *
  * Behavior (FUN_WITH_RUST=ON):

src/vm/rust/hello_args.c

@@ -15,9 +15,6 @@
  * string, calls into Rust to print/log it, and pushes Nil. When Rust support is
  * disabled, the argument is still popped and freed to keep the stack sane,
  * then Nil is pushed after raising an error message.
- */
-
-/**
  * OP_RUST_HELLO_ARGS: (msg:any) -> Nil
  *
  * Behavior (FUN_WITH_RUST=ON):
@@ -31,6 +28,7 @@
  * - Raises a runtime error indicating missing Rust support.
  * - Pushes Nil.
  */
+
 case OP_RUST_HELLO_ARGS: {
 #ifdef FUN_WITH_RUST
   Value vmsg = pop_value(vm);

src/vm/rust/hello_args_return.c

@@ -15,9 +15,7 @@
  * converts it to a C string, passes it to Rust, and pushes back the string
  * returned by Rust. If Rust returns NULL or Rust support is disabled, Nil is
  * pushed.
- */
+ * 
-
-/**
  * OP_RUST_HELLO_ARGS_RETURN: (msg:any) -> string | Nil
  *
  * Behavior (FUN_WITH_RUST=ON):
@@ -33,6 +31,7 @@
  * - Raises a runtime error indicating missing Rust support.
  * - Pushes Nil.
  */
+
 case OP_RUST_HELLO_ARGS_RETURN: {
 #ifdef FUN_WITH_RUST
   Value vmsg = pop_value(vm);

src/vm/rust/set_exit.c

@@ -15,9 +15,7 @@
  * vm.exit_code. Pushes Nil afterwards. When Rust support is disabled, the
  * argument is still popped/freed, a runtime error is raised, and Nil is
  * pushed to maintain stack discipline.
- */
+ * 
-
-/**
  * OP_RUST_SET_EXIT: (code:int) -> Nil
  *
  * Behavior (FUN_WITH_RUST=ON):
@@ -30,6 +28,7 @@
  * - Raises a runtime error indicating missing Rust support.
  * - Pushes Nil.
  */
+
 case OP_RUST_SET_EXIT: {
 #ifdef FUN_WITH_RUST
   extern int fun_op_rset_exit(VM * vm);

src/vm/sqlite/close.c

@@ -13,11 +13,10 @@
  *
  * Closes a registered SQLite database handle and unregisters it when
  * FUN_WITH_SQLITE is enabled. No-op when SQLite support is disabled.
- */
+ * 
-
-/**
  * OP_SQLITE_CLOSE: (handle:int) -> Nil
  */
+
 case OP_SQLITE_CLOSE: {
 #ifdef FUN_WITH_SQLITE
   Value vh = pop_value(vm);

src/vm/sqlite/exec.c

@@ -13,11 +13,10 @@
  *
  * Executes a SQL statement against an open SQLite handle when
  * FUN_WITH_SQLITE is enabled. Returns the SQLite result code.
- */
+ * 
-
-/**
  * OP_SQLITE_EXEC: (handle:int, sql:string) -> int rc (0=OK)
  */
+
 case OP_SQLITE_EXEC: {
 #ifdef FUN_WITH_SQLITE
   Value vsql = pop_value(vm);

src/vm/sqlite/open.c

@@ -13,11 +13,10 @@
  *
  * Opens a SQLite database and registers a handle when FUN_WITH_SQLITE is
  * enabled. On failure or when SQLite support is disabled, pushes 0.
- */
+ * 
-
-/**
  * OP_SQLITE_OPEN: (path:string) -> handle:int (>0) or 0 on error
  */
+
 case OP_SQLITE_OPEN: {
 #ifdef FUN_WITH_SQLITE
   Value vpath = pop_value(vm);

src/vm/sqlite/query.c

@@ -13,11 +13,10 @@
  *
  * Prepares and steps through a SQLite statement to produce an array of row
  * maps when FUN_WITH_SQLITE is enabled. Returns an empty array otherwise.
- */
+ * 
-
-/**
  * OP_SQLITE_QUERY: (handle:int, sql:string) -> array<map<string,any>>
  */
+
 case OP_SQLITE_QUERY: {
 #ifdef FUN_WITH_SQLITE
   Value vsql = pop_value(vm);

src/vm/strings/find.c

@@ -24,12 +24,9 @@
  * - Exits with an error if the operands are not strings.
  *
  * Example:
- * // Bytecode: OP_FIND
+ * - Bytecode: OP_FIND
- * // Stack before: ["world", "hello world"]
+ * - Stack before: ["world", "hello world"]
- * // Stack after: [6]
+ * - Stack after: [6]
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_FIND: {

src/vm/strings/regex_match.c

@@ -31,6 +31,7 @@
  * - pattern = "[a-z]+", input = "hello"  -> 1
  * - pattern = "[a-z]+", input = "hello!" -> 0 (not a full match)
  */
+
 /* Regex full-match opcode using POSIX regex */
 #ifdef __unix__
 #include <regex.h>

src/vm/strings/regex_replace.c

@@ -31,6 +31,7 @@
  * Example:
  * - pattern = "[0-9]+", repl = "#", input = "a1b22c" -> "a#b#c"
  */
+
 /* Regex global replace opcode using POSIX regex */
 #ifdef __unix__
 #include <regex.h>

src/vm/strings/regex_search.c

@@ -34,6 +34,7 @@
  * - pattern = "h(ell)o", input = "oh hello!" ->
  *   { match: "hello", start: 3, end: 8, groups: ["ell"] }
  */
+
 /* Regex search (first match) opcode using POSIX regex */
 #ifdef __unix__
 #include <regex.h>

src/vm/strings/split.c

@@ -24,12 +24,9 @@
  * - Exits with an error if the operands are not strings.
  *
  * Example:
- * // Bytecode: OP_SPLIT
+ * - Bytecode: OP_SPLIT
- * // Stack before: [", ", "a, b, c"]
+ * - Stack before: [", ", "a, b, c"]
- * // Stack after: [["a", "b", "c"]]
+ * - Stack after: [["a", "b", "c"]]
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_SPLIT: {

src/vm/strings/substr.c

@@ -25,12 +25,9 @@
  * - Exits with an error if the start index or length is out of bounds.
  *
  * Example:
- * // Bytecode: OP_SUBSTR
+ * - Bytecode: OP_SUBSTR
- * // Stack before: [5, 6, "hello world"]
+ * - Stack before: [5, 6, "hello world"]
- * // Stack after: ["world"]
+ * - Stack after: ["world"]
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_SUBSTR: {

src/vm/to_number.c

@@ -23,12 +23,9 @@
  * - Exits with an error if the conversion fails.
  *
  * Example:
- * // Bytecode: OP_TO_NUMBER
+ * - Bytecode: OP_TO_NUMBER
- * // Stack before: ["42"]
+ * - Stack before: ["42"]
- * // Stack after: [42]
+ * - Stack after: [42]
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_TO_NUMBER: {

src/vm/to_string.c

@@ -29,12 +29,9 @@
  * - Exits with an error if memory allocation fails during string creation.
  *
  * Example:
- * // Bytecode: OP_TO_STRING
+ * - Bytecode: OP_TO_STRING
- * // Stack before: [42]
+ * - Stack before: [42]
- * // Stack after: ["42"]
+ * - Stack after: ["42"]
- *
- * @author Johannes Findeisen
- * @date 2025-10-16
  */
 
 case OP_TO_STRING: {

src/vm/xml/name.c

@@ -30,9 +30,10 @@
  *   stack as usual.
  *
  * Example
- *  // ... stack: [ node_handle ]
+ *  - stack: [ node_handle ]
- *  OP_XML_NAME  // → [ "book" ]
+ *  - OP_XML_NAME → [ "book" ]
  */
+
 /* OP_XML_NAME: pops node handle; pushes string */
 case OP_XML_NAME: {
 #ifdef FUN_WITH_XML2

src/vm/xml/parse.c

@@ -28,9 +28,10 @@
  * - The parser is invoked with XML_PARSE_NONET to disallow network access.
  *
  * Example
- *  // stack: [ "<root/>" ]
+ *  - stack: [ "<root/>" ]
- *  OP_XML_PARSE   // → [ 1 ]   (example handle)
+ *  - OP_XML_PARSE  → [ 1 ]   (example handle)
  */
+
 /* OP_XML_PARSE: pops text string; pushes doc handle (>0) or 0 */
 case OP_XML_PARSE: {
 #ifdef FUN_WITH_XML2

src/vm/xml/root.c

@@ -26,9 +26,10 @@
  *   released by corresponding XML VM opcodes to avoid leaks.
  *
  * Example
- *  // stack: [ doc_handle ]
+ *  - stack: [ doc_handle ]
- *  OP_XML_ROOT   // → [ node_handle ] or [ 0 ]
+ *  - OP_XML_ROOT → [ node_handle ] or [ 0 ]
  */
+
 /* OP_XML_ROOT: pops doc handle; pushes node handle (>0) or 0 */
 case OP_XML_ROOT: {
 #ifdef FUN_WITH_XML2

src/vm/xml/text.c

@@ -27,9 +27,10 @@
  *   freed immediately after use.
  *
  * Example
- *  // stack: [ node_handle ]
+ *  - stack: [ node_handle ]
- *  OP_XML_TEXT   // → [ "Hello world" ]
+ *  - OP_XML_TEXT → [ "Hello world" ]
  */
+
 /* OP_XML_TEXT: pops node handle; pushes string (concatenate text node children) */
 case OP_XML_TEXT: {
 #ifdef FUN_WITH_XML2