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

src/vm/pcre2/findall.c

@@ -5,8 +5,40 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file findall.c
+ * @brief Implements the OP_PCRE2_FINDALL opcode (conditional build).
  *
- * Added: 2025-11-25
+ * Finds all non-overlapping matches of a PCRE2 pattern in a subject string
+ * and returns an array of maps describing each match when FUN_WITH_PCRE2 is
+ * enabled. When PCRE2 support is disabled at build time, the opcode falls
+ * back to returning an empty array.
+ */
+
+/**
+ * OP_PCRE2_FINDALL: (pattern:any, text:any, flags:int|bool=0) -> array(map)
+ *
+ * Behavior when FUN_WITH_PCRE2 is enabled:
+ * - Pops three arguments from the VM stack: pattern, text, flags.
+ *   - pattern and text are converted to strings using value_to_string_alloc().
+ *   - flags bits map to PCRE2 options:
+ *     - 1 = PCRE2_CASELESS (I)
+ *     - 2 = PCRE2_MULTILINE (M)
+ *     - 4 = PCRE2_DOTALL (S)
+ *     - 8 = PCRE2_UTF (U)
+ *     - 16 = PCRE2_EXTENDED (X)
+ * - Compiles the pattern and scans the subject for all non-overlapping
+ *   matches. For each match, pushes into the result array a map with keys:
+ *   - "full": matched substring (group 0)
+ *   - "start": start index (int)
+ *   - "end": end index (int, exclusive)
+ *   - "groups": array of captured group strings (excluding group 0)
+ * - On compilation error or allocation failure, returns an empty array.
+ *
+ * Behavior when FUN_WITH_PCRE2 is disabled:
+ * - Pops three values and returns an empty array.
  */
 
 /* PCRE2_FINDALL */

src/vm/pcre2/match.c

@@ -5,8 +5,38 @@
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
+ */
+
+/**
+ * @file match.c
+ * @brief Implements the OP_PCRE2_MATCH opcode (conditional build).
  *
- * Added: 2025-11-25
+ * Executes a single PCRE2 pattern match against a subject string and returns
+ * a map describing the first match and its capture groups when FUN_WITH_PCRE2
+ * is enabled. Returns Nil when there is no match or on error. When PCRE2
+ * support is disabled at build time, the opcode always returns Nil.
+ */
+
+/**
+ * OP_PCRE2_MATCH: (pattern:any, text:any, flags:int|bool=0) -> map|Nil
+ *
+ * Behavior when FUN_WITH_PCRE2 is enabled:
+ * - Pops: pattern, text, flags. Converts pattern/text to strings.
+ * - Flags bits:
+ *   - 1 = PCRE2_CASELESS (I)
+ *   - 2 = PCRE2_MULTILINE (M)
+ *   - 4 = PCRE2_DOTALL (S)
+ *   - 8 = PCRE2_UTF (U)
+ *   - 16 = PCRE2_EXTENDED (X)
+ * - On successful match, returns a map with keys:
+ *   - "full": matched substring (group 0)
+ *   - "start": start index (int)
+ *   - "end": end index (int, exclusive)
+ *   - "groups": array of captured group strings (excluding group 0)
+ * - On no match or compile error, returns Nil.
+ *
+ * Behavior when FUN_WITH_PCRE2 is disabled:
+ * - Pops three values and returns Nil.
  */
 
 /* PCRE2_MATCH */

src/vm/pcre2/test.c

@@ -9,6 +9,33 @@
  * Added: 2025-11-25
  */
 
+/**
+ * @file test.c
+ * @brief Implements the OP_PCRE2_TEST opcode (conditional build).
+ *
+ * Tests whether a PCRE2 pattern matches a subject string and returns 1 on
+ * success or 0 otherwise when FUN_WITH_PCRE2 is enabled. When PCRE2 support
+ * is disabled at build time, the opcode always returns 0.
+ */
+
+/**
+ * OP_PCRE2_TEST: (pattern:any, text:any, flags:int|bool=0) -> int
+ *
+ * Behavior when FUN_WITH_PCRE2 is enabled:
+ * - Pops: pattern, text, flags. Converts pattern/text to strings.
+ * - Flags bits:
+ *   - 1 = PCRE2_CASELESS (I)
+ *   - 2 = PCRE2_MULTILINE (M)
+ *   - 4 = PCRE2_DOTALL (S)
+ *   - 8 = PCRE2_UTF (U)
+ *   - 16 = PCRE2_EXTENDED (X)
+ * - Returns 1 if pcre2_match() returns a non-negative result, else 0.
+ * - On compile error or allocation failure, returns 0.
+ *
+ * Behavior when FUN_WITH_PCRE2 is disabled:
+ * - Pops three values and returns 0.
+ */
+
 /* PCRE2_TEST */
 case OP_PCRE2_TEST: {
 #ifdef FUN_WITH_PCRE2