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

src/vm/xml/name.c

@@ -1,14 +1,38 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-09
  */
 
+/**
+ * @file
+ * @brief VM opcode snippet for XML node name retrieval.
+ *
+ * This file is included into the main VM dispatch switch in vm.c and
+ * implements the OP_XML_NAME instruction.
+ *
+ * Opcode: OP_XML_NAME
+ * - Stack effect: pop (int node_handle) → push (string name)
+ * - Success: pushes the element/node name as a string. If the node has no
+ *   name, an empty string is pushed.
+ * - Errors/edge cases: if the handle is invalid or the node cannot be
+ *   retrieved, an empty string is pushed. The instruction does not throw.
+ * - Gating: When FUN_WITH_XML2 is not enabled at build time, the operand is
+ *   still popped and an empty string is pushed.
+ *
+ * Notes
+ * - Node handles are small positive integers managed by the XML handle
+ *   registry defined in the xml2 extension (see extensions/xml2.c).
+ * - The pushed string is a new VM value; ownership is transferred to the VM
+ *   stack as usual.
+ *
+ * Example
+ *  // ... stack: [ node_handle ]
+ *  OP_XML_NAME  // → [ "book" ]
+ */
 /* OP_XML_NAME: pops node handle; pushes string */
 case OP_XML_NAME: {
 #ifdef FUN_WITH_XML2

src/vm/xml/parse.c

@@ -1,14 +1,36 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-09
  */
 
+/**
+ * @file
+ * @brief VM opcode snippet for parsing XML text into a document handle.
+ *
+ * This snippet is included by vm.c and implements OP_XML_PARSE.
+ *
+ * Opcode: OP_XML_PARSE
+ * - Stack effect: pop (string xml_text) → push (int doc_handle | 0)
+ * - Behavior: Parses the given XML string into an in-memory xmlDoc.
+ *   On success, a positive document handle is allocated via the XML handle
+ *   registry and pushed. On failure (malformed XML, OOM), 0 is pushed.
+ * - Initialization: Ensures libxml2 is initialized once (xmlInitParser()).
+ * - Gating: If FUN_WITH_XML2 is disabled, the input is discarded and 0 is
+ *   pushed.
+ *
+ * Notes
+ * - The handle must later be released via appropriate XML VM opcodes that
+ *   free documents; leaking handles will leak memory.
+ * - The parser is invoked with XML_PARSE_NONET to disallow network access.
+ *
+ * Example
+ *  // stack: [ "<root/>" ]
+ *  OP_XML_PARSE   // → [ 1 ]   (example handle)
+ */
 /* OP_XML_PARSE: pops text string; pushes doc handle (>0) or 0 */
 case OP_XML_PARSE: {
 #ifdef FUN_WITH_XML2

src/vm/xml/root.c

@@ -1,14 +1,34 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-09
  */
 
+/**
+ * @file
+ * @brief VM opcode snippet for retrieving the root node of an XML document.
+ *
+ * Included by vm.c; implements OP_XML_ROOT.
+ *
+ * Opcode: OP_XML_ROOT
+ * - Stack effect: pop (int doc_handle) → push (int node_handle | 0)
+ * - Behavior: For a valid document handle, obtains the document's root
+ *   element and returns a positive node handle. If the document is invalid
+ *   or has no root element, 0 is pushed.
+ * - Gating: If FUN_WITH_XML2 is disabled, the input is discarded and 0 is
+ *   pushed.
+ *
+ * Notes
+ * - Returned node handles are managed by the XML node registry. They must be
+ *   released by corresponding XML VM opcodes to avoid leaks.
+ *
+ * Example
+ *  // stack: [ doc_handle ]
+ *  OP_XML_ROOT   // → [ node_handle ] or [ 0 ]
+ */
 /* OP_XML_ROOT: pops doc handle; pushes node handle (>0) or 0 */
 case OP_XML_ROOT: {
 #ifdef FUN_WITH_XML2

src/vm/xml/text.c

@@ -1,14 +1,35 @@
-/*
+/**
  * This file is part of the Fun programming language.
  * https://fun-lang.xyz/
  *
  * Copyright 2025 Johannes Findeisen <you@hanez.org>
  * Licensed under the terms of the Apache-2.0 license.
  * https://opensource.org/license/apache-2-0
- *
- * Added: 2025-12-09
  */
 
+/**
+ * @file
+ * @brief VM opcode snippet for retrieving the concatenated text of an XML node.
+ *
+ * Included by vm.c; implements OP_XML_TEXT.
+ *
+ * Opcode: OP_XML_TEXT
+ * - Stack effect: pop (int node_handle) → push (string text)
+ * - Behavior: Retrieves the node's textual content as produced by
+ *   xmlNodeGetContent(), which concatenates all descendant text nodes.
+ *   If the node is invalid or has no textual content, an empty string is
+ *   pushed.
+ * - Gating: If FUN_WITH_XML2 is disabled, the input is discarded and an empty
+ *   string is pushed.
+ *
+ * Notes
+ * - The returned string is copied into a VM string value; libxml2 buffers are
+ *   freed immediately after use.
+ *
+ * Example
+ *  // stack: [ node_handle ]
+ *  OP_XML_TEXT   // → [ "Hello world" ]
+ */
 /* OP_XML_TEXT: pops node handle; pushes string (concatenate text node children) */
 case OP_XML_TEXT: {
 #ifdef FUN_WITH_XML2