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

src/vm/json/from_file.c

@@ -5,8 +5,30 @@
  * 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 from_file.c
+ * @brief VM opcode snippet for loading a JSON document from a file.
  *
- * Added: 2025-11-24
+ * This snippet is included by vm.c and implements the OP_JSON_FROM_FILE
+ * instruction. It expects a path on the VM stack, reads the file using
+ * json-c, converts the resulting json_object tree into a Fun Value, and
+ * pushes that Value back on the VM stack.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled (json-c
+ * available). When disabled, the opcode consumes its argument (if any)
+ * and pushes Nil.
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: path (any; converted to string)
+ * - Pushes: Value converted from JSON, or Nil on error
+ *
+ * Errors and edge cases:
+ * - If the path cannot be converted to a C string or json_object_from_file
+ *   fails (e.g., missing file, invalid JSON), the opcode pushes Nil.
+ * - The created json_object is released after conversion; ownership of the
+ *   pushed Fun Value follows normal VM semantics.
  */
 
 /* JSON_FROM_FILE */

src/vm/json/parse.c

@@ -5,8 +5,28 @@
  * 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 parse.c
+ * @brief VM opcode snippet for parsing a JSON string into a Fun Value.
  *
- * Added: 2025-11-24
+ * Implements the OP_JSON_PARSE instruction. Expects a string (or any value
+ * convertible to string) on the stack, parses it with json-c, converts the
+ * resulting json_object to a Fun Value and pushes it.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled. Otherwise the
+ * opcode consumes its argument and pushes Nil.
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: text (any; converted to string)
+ * - Pushes: Value converted from JSON, or Nil on error
+ *
+ * Errors and edge cases:
+ * - If allocation fails, tokenization fails, or the text is not valid JSON,
+ *   the opcode pushes Nil.
+ * - The temporary json-c objects are released after conversion; ownership of
+ *   the pushed Fun Value follows normal VM semantics.
  */
 
 /* JSON_PARSE */

src/vm/json/stringify.c

@@ -5,8 +5,27 @@
  * 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 stringify.c
+ * @brief VM opcode snippet for converting a Fun Value to a JSON string.
  *
- * Added: 2025-11-24
+ * Implements the OP_JSON_STRINGIFY instruction. Expects a boolean/integer flag
+ * indicating pretty-printing and a Value to serialize. Uses json-c to build a
+ * json_object from the Value and then renders it to a string, which is pushed
+ * back to the stack.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled. Otherwise the
+ * opcode consumes its two arguments and pushes the string "null".
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: pretty (bool/int), value (any)
+ * - Pushes: string (JSON representation)
+ *
+ * Errors and edge cases:
+ * - If conversion to json_object fails, an empty string is pushed.
+ * - Pretty printing selects JSON_C_TO_STRING_PRETTY; otherwise plain output.
  */
 
 /* JSON_STRINGIFY */

src/vm/json/to_file.c

@@ -5,8 +5,27 @@
  * 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 to_file.c
+ * @brief VM opcode snippet for writing a Fun Value as JSON to a file.
  *
- * Added: 2025-11-24
+ * Implements the OP_JSON_TO_FILE instruction. Expects a pretty-print flag,
+ * a Value to serialize, and a path. Serializes the Value via json-c and
+ * writes it to the specified file path.
+ *
+ * Build gating: compiled only when FUN_WITH_JSON is enabled. Otherwise the
+ * opcode consumes three arguments and pushes 0 (failure).
+ *
+ * Stack effect (with FUN_WITH_JSON):
+ * - Pops: pretty (bool/int), value (any), path (any; converted to string)
+ * - Pushes: int (1 on success, 0 on failure)
+ *
+ * Errors and edge cases:
+ * - If the path cannot be converted to a C string or file writing fails,
+ *   the opcode pushes 0.
+ * - Pretty printing selects JSON_C_TO_STRING_PRETTY; otherwise plain output.
  */
 
 /* JSON_TO_FILE */