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

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]
  *