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

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) {