Added tons of opcode documentation, changed license to ISC and a lot of file refactoring.

src/vm/core/call.c

@@ -1,3 +1,32 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file call.c
+ * @brief Implements the OP_CALL opcode for function calls in the VM.
+ *
+ * This file handles the OP_CALL instruction, which calls a function with arguments.
+ *
+ * Behavior:
+ * - operand specifies number of arguments
+ * - Pops args and function from stack
+ * - Creates new frame with args in locals
+ * - Sets IP to start of function
+ *
+ * Error Handling:
+ * - Exits with error if not enough args
+ * - Exits if function isn't callable
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_CALL: {
     int argc = inst.operand;
     if (argc < 0) argc = 0;

src/vm/core/dup.c

@@ -1,3 +1,35 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file dup.c
+ * @brief Implements the OP_DUP opcode for duplicating the top stack value in the VM.
+ *
+ * This file handles the OP_DUP instruction, which duplicates the top value on the stack.
+ * The duplicated value is pushed back onto the stack.
+ *
+ * Behavior:
+ * - Duplicates the top value on the stack.
+ * - Pushes the duplicated value onto the stack.
+ *
+ * Error Handling:
+ * - Exits with an error if the stack is empty.
+ *
+ * Example:
+ * // Bytecode: OP_DUP
+ * // Stack before: [42]
+ * // Stack after: [42, 42]
+*
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_DUP: {
     if (vm->sp < 0) {
         fprintf(stderr, "Runtime error: stack underflow for DUP\n");

src/vm/core/halt.c

@@ -1,2 +1,30 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file halt.c
+ * @brief Implements the OP_HALT opcode for stopping VM execution.
+ *
+ * This file handles the OP_HALT instruction, which stops the execution of the VM.
+ * No stack operations are performed.
+ *
+ * Behavior:
+ * - Stops the VM execution immediately.
+ *
+ * Example:
+ * // Bytecode: OP_HALT
+ * // Stack before: [42]
+ * // Stack after: [42]
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_HALT:
     return;

src/vm/core/jump.c

@@ -1,3 +1,32 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file jump.c
+ * @brief Implements the OP_JUMP opcode for unconditional jumps in the VM.
+ *
+ * This file handles the OP_JUMP instruction, which performs an unconditional
+ * jump to a new instruction pointer location.
+ *
+ * Behavior:
+ * - Sets IP to operand value
+ * - No stack manipulation
+ *
+ * Used for:
+ * - Loops
+ * - Function returns
+ * - Conditional control flow
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_JUMP: {
     f->ip = inst.operand;
     break;

src/vm/core/jump_if_false.c

@@ -1,3 +1,33 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file jump_if_false.c
+ * @brief Implements the OP_JUMP_IF_FALSE opcode for conditional jumps in the VM.
+ *
+ * This file handles the OP_JUMP_IF_FALSE instruction, which jumps if the top
+ * stack value is falsey (0, false, nil, etc).
+ *
+ * Behavior:
+ * - Pops condition value from stack
+ * - Jumps to operand IP if falsey
+ * - Continues normally if truthy
+ *
+ * Used for:
+ * - If statements
+ * - While loops
+ * - Logical expressions
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_JUMP_IF_FALSE: {
     Value cond = pop_value(vm);
     int truthy = value_is_truthy(&cond);

src/vm/core/load_const.c

@@ -1,3 +1,30 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file load_const.c
+ * @brief Implements the OP_LOAD_CONST opcode for loading constants in the VM.
+ *
+ * This file handles the OP_LOAD_CONST instruction, which loads a constant value
+ * from the bytecode's constant pool onto the stack.
+ *
+ * Behavior:
+ * - operand is index into constant pool
+ * - Pushes copy of constant onto stack
+ *
+ * Error Handling:
+ * - Exits if invalid constant index
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_LOAD_CONST: {
     int idx = inst.operand;
     if (idx < 0 || idx >= f->fn->const_count) {

src/vm/core/load_global.c

@@ -1,3 +1,35 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file load_global.c
+ * @brief Implements the OP_LOAD_GLOBAL opcode for loading global variables in the VM.
+ *
+ * This file handles the OP_LOAD_GLOBAL instruction, which loads a global variable
+ * onto the stack using its index.
+ *
+ * Behavior:
+ * - Loads the global variable at the specified index.
+ * - Pushes the value onto the stack.
+ *
+ * Error Handling:
+ * - Exits with an error if the index is out of bounds.
+ *
+ * Example:
+ * // Bytecode: OP_LOAD_GLOBAL 0
+ * // Stack before: []
+ * // Stack after: [global_value]
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_LOAD_GLOBAL: {
     int idx = inst.operand;
     if (idx < 0 || idx >= VM_MAX_GLOBALS) {

src/vm/core/load_local.c

@@ -1,3 +1,35 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file load_local.c
+ * @brief Implements the OP_LOAD_LOCAL opcode for loading local variables in the VM.
+ *
+ * This file handles the OP_LOAD_LOCAL instruction, which loads a local variable
+ * onto the stack using its index.
+ *
+ * Behavior:
+ * - Loads the local variable at the specified index.
+ * - Pushes the value onto the stack.
+ *
+ * Error Handling:
+ * - Exits with an error if the index is out of bounds.
+ *
+ * Example:
+ * // Bytecode: OP_LOAD_LOCAL 0
+ * // Stack before: []
+ * // Stack after: [local_value]
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_LOAD_LOCAL: {
     int slot = inst.operand;
     if (slot < 0 || slot >= FRAME_MAX_LOCALS) {

src/vm/core/nop.c

@@ -1,2 +1,30 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file nop.c
+ * @brief Implements the OP_NOP opcode for no operation in the VM.
+ *
+ * This file handles the OP_NOP instruction, which performs no operation.
+ * The stack remains unchanged.
+ *
+ * Behavior:
+ * - Does nothing.
+ *
+ * Example:
+ * // Bytecode: OP_NOP
+ * // Stack before: [42]
+ * // Stack after: [42]
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_NOP:
     break;

src/vm/core/pop.c

@@ -1,3 +1,33 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file pop.c
+ * @brief Implements the OP_POP opcode for removing the top stack value in the VM.
+ *
+ * This file handles the OP_POP instruction, which removes the top value from the stack.
+ *
+ * Behavior:
+ * - Removes the top value from the stack.
+ *
+ * Error Handling:
+ * - Exits with an error if the stack is empty.
+ *
+ * Example:
+ * // Bytecode: OP_POP
+ * // Stack before: [42]
+ * // Stack after: []
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_POP: {
     if (vm->sp < 0) {
         fprintf(stderr, "Runtime error: stack underflow for POP\n");

src/vm/core/return.c

@@ -1,3 +1,36 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file return.c
+ * @brief Implements the OP_RETURN opcode for returning from a function in the VM.
+ *
+ * This file handles the OP_RETURN instruction, which returns from the current function
+ * and optionally pushes a return value onto the stack.
+ *
+ * Behavior:
+ * - Pops the optional return value from the stack.
+ * - Returns to the caller frame.
+ * - Pushes the return value onto the stack (if any).
+ *
+ * Error Handling:
+ * - Exits with an error if the frame stack is empty.
+ *
+ * Example:
+ * // Bytecode: OP_RETURN
+ * // Stack before: [42]
+ * // Stack after: [42]
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_RETURN: {
     Value retv;
     if (vm->sp >= 0) retv = pop_value(vm);

src/vm/core/store_global.c

@@ -1,3 +1,35 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file store_global.c
+ * @brief Implements the OP_STORE_GLOBAL opcode for storing global variables in the VM.
+ *
+ * This file handles the OP_STORE_GLOBAL instruction, which stores a value into a global variable
+ * using its index.
+ *
+ * Behavior:
+ * - Pops the value from the stack.
+ * - Stores the value into the global variable at the specified index.
+ *
+ * Error Handling:
+ * - Exits with an error if the index is out of bounds.
+ *
+ * Example:
+ * // Bytecode: OP_STORE_GLOBAL 0
+ * // Stack before: [42]
+ * // Stack after: []
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_STORE_GLOBAL: {
     int idx = inst.operand;
     if (idx < 0 || idx >= VM_MAX_GLOBALS) {

src/vm/core/store_local.c

@@ -1,3 +1,35 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file store_local.c
+ * @brief Implements the OP_STORE_LOCAL opcode for storing local variables in the VM.
+ *
+ * This file handles the OP_STORE_LOCAL instruction, which stores a value into a local variable
+ * using its index.
+ *
+ * Behavior:
+ * - Pops the value from the stack.
+ * - Stores the value into the local variable at the specified index.
+ *
+ * Error Handling:
+ * - Exits with an error if the index is out of bounds.
+ *
+ * Example:
+ * // Bytecode: OP_STORE_LOCAL 0
+ * // Stack before: [42]
+ * // Stack after: []
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_STORE_LOCAL: {
     int slot = inst.operand;
     if (slot < 0 || slot >= FRAME_MAX_LOCALS) {

src/vm/core/swap.c

@@ -1,3 +1,30 @@
+/**
+ * This file is part of the Fun programming language.
+ * https://hanez.org/project/fun/
+ *
+ * Copyright 2025 Johannes Findeisen <you@hanez.org>
+ * Licensed under the terms of the ISC license.
+ * https://opensource.org/license/isc-license-txt
+ */
+
+/**
+* @file swap.c
+ * @brief Implements the OP_SWAP opcode for stack manipulation in the VM.
+ *
+ * This file handles the OP_SWAP instruction, which swaps the top two values
+ * on the stack.
+ *
+ * Behavior:
+ * - Swaps stack[sp] and stack[sp-1]
+ * - No type checking
+ *
+ * Error Handling:
+ * - Exits if stack underflow
+ *
+ * @author Johannes Findeisen
+ * @date 2025-10-16
+ */
+
 case OP_SWAP: {
     if (vm->sp < 1) {
         fprintf(stderr, "Runtime error: stack underflow for SWAP\n");