Added documentation to kcgi opcodes as Doxygen compatible comments. No code changes. (0.41.10)

src/vm/kcgi/end.c

@@ -1,3 +1,26 @@
+/*
+ * 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
+ */
+
+/**
+ * @file end.c
+ * @brief VM opcode snippet to finalize kcgi handling and release state.
+ *
+ * This snippet is included by vm.c and implements the OP_KCGI_END
+ * instruction. When FUN_WITH_KCGI is enabled, it releases any currently
+ * stored request (g_kcgi_req) and pushes 1, indicating success. When kcgi
+ * support is disabled, it simply pushes 0.
+ *
+ * Stack effect:
+ * - Pops: (none)
+ * - Pushes: int 1 when FUN_WITH_KCGI, otherwise int 0
+ */
+
 /* KCGI_END */
 case OP_KCGI_END: {
 #ifdef FUN_WITH_KCGI

src/vm/kcgi/parse.c

@@ -1,3 +1,31 @@
+/*
+ * 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
+ */
+
+/**
+ * @file parse.c
+ * @brief VM opcode snippet for parsing the incoming HTTP request via kcgi.
+ *
+ * This snippet is included by vm.c and implements the OP_KCGI_PARSE
+ * instruction. It invokes kcgi to parse the current HTTP request. If a
+ * previous request object exists in g_kcgi_req, it is freed first to avoid
+ * leaks. On success, the global g_kcgi_req is updated and the parsed request
+ * is converted to a Fun Value via kreq_to_fun() and pushed onto the stack.
+ * On failure, Nil is pushed.
+ *
+ * Build gating: compiled only when FUN_WITH_KCGI is enabled. When disabled,
+ * the opcode simply pushes Nil.
+ *
+ * Stack effect (with FUN_WITH_KCGI):
+ * - Pops: (none)
+ * - Pushes: Fun Value representing the request on success, or Nil on error
+ */
+
 /* KCGI_PARSE */
 case OP_KCGI_PARSE: {
 #ifdef FUN_WITH_KCGI

src/vm/kcgi/reply_start.c

@@ -1,3 +1,32 @@
+/*
+ * 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
+ */
+
+/**
+ * @file reply_start.c
+ * @brief VM opcode snippet to start an HTTP reply using kcgi.
+ *
+ * This snippet is included by vm.c and implements the OP_KCGI_REPLY_START
+ * instruction. It pops two values from the stack: the content type and an
+ * HTTP status code. Values are converted leniently (int/float/string to code;
+ * any value to string for the content type). If the content type is missing
+ * or empty, a default of "text/html; charset=utf-8" is used. The opcode then
+ * calls kcgi_reply_start(code, content_type) and pushes 1 on success or 0 on
+ * failure.
+ *
+ * Build gating: compiled only when FUN_WITH_KCGI is enabled. When disabled,
+ * the opcode consumes both arguments and pushes 0.
+ *
+ * Stack effect (with FUN_WITH_KCGI):
+ * - Pops: content_type (any; converted to string), status_code (int|float|string)
+ * - Pushes: int 1 on success, int 0 on failure
+ */
+
 /* KCGI_REPLY_START */
 case OP_KCGI_REPLY_START: {
 #ifdef FUN_WITH_KCGI

src/vm/kcgi/write.c

@@ -1,3 +1,33 @@
+/*
+ * 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
+ */
+
+/**
+ * @file write.c
+ * @brief VM opcode snippet for writing HTTP response body via kcgi.
+ *
+ * This snippet is included by vm.c and implements the OP_KCGI_WRITE
+ * instruction. It pops one value, converts it to a UTF-8 string, and
+ * writes it to the HTTP response using kcgi_write_str(). It then pushes
+ * 1 on success or 0 on failure.
+ *
+ * Build gating: compiled only when FUN_WITH_KCGI is enabled. When disabled,
+ * the opcode consumes its argument (if any) and pushes 0.
+ *
+ * Stack effect (with FUN_WITH_KCGI):
+ * - Pops: text (any; converted to string; empty string if NULL)
+ * - Pushes: int 1 on success, int 0 on failure
+ *
+ * Notes:
+ * - Ownership: A temporary C string is allocated for conversion and freed
+ *   after the write. The pushed Value follows normal VM ownership rules.
+ */
+
 /* KCGI_WRITE */
 case OP_KCGI_WRITE: {
 #ifdef FUN_WITH_KCGI