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

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