From f45540a10c6fc1fefed50443e49e4585e12c18ad Mon Sep 17 00:00:00 2001
From: Marcono1234 <Marcono1234@users.noreply.github.com>
Date: Mon, 10 Aug 2026 23:45:48 +0200
Subject: [PATCH] Document `Parser` and `Instance` exception behavior

---
 .../java/run/endive/runtime/Instance.java     | 17 +++++++++++
 .../java/run/endive/runtime/OpcodeImpl.java   | 10 +++----
 .../src/main/java/run/endive/wasm/Parser.java | 28 +++++++++++++++++++
 3 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/runtime/src/main/java/run/endive/runtime/Instance.java b/runtime/src/main/java/run/endive/runtime/Instance.java
index e9d5f57e4..027f91a59 100644
--- a/runtime/src/main/java/run/endive/runtime/Instance.java
+++ b/runtime/src/main/java/run/endive/runtime/Instance.java
@@ -1072,6 +1072,23 @@ private Map<String, Export> genExports(ExportSection export) {
             return exports;
         }
 
+        /**
+         * Builds the instance.
+         *
+         * <p>If building fails, for example due to invalid or unsupported Wasm code, an exception
+         * is thrown. In many cases that exception will be a {@link WasmEngineException} or a
+         * subclass of it, but callers should be prepared to handle any kind of {@code
+         * RuntimeException}.<br>
+         * When such exceptions occur depends on how the code is compiled and executed:
+         *
+         * <ul>
+         *   <li>runtime compilation: many exceptions are thrown already when this {@code build()}
+         *       method is called
+         *   <li>interpreter: many exceptions are only thrown once the Wasm code is executed
+         * </ul>
+         *
+         * @throws RuntimeException if the Wasm code is invalid or contains unsupported instructions
+         */
         public Instance build() {
             Map<String, Export> exports = genExports(module.exportSection());
             var globalInitializers = module.globalSection().globals();
diff --git a/runtime/src/main/java/run/endive/runtime/OpcodeImpl.java b/runtime/src/main/java/run/endive/runtime/OpcodeImpl.java
index 450c68128..f92c854db 100644
--- a/runtime/src/main/java/run/endive/runtime/OpcodeImpl.java
+++ b/runtime/src/main/java/run/endive/runtime/OpcodeImpl.java
@@ -917,12 +917,10 @@ public static long unboxFromTable(int tableValue, Instance instance, ValType ele
             impl = java.lang.invoke.VarHandle::fullFence;
         } catch (NoSuchMethodError e) {
             try {
-                // Suppress IntelliJ warning about module-info.java needing `requires
-                // jdk.unsupported` for
-                // `sun.misc.Unsafe`. This code here is only a fallback when `VarHandle::fullFence`
-                // is unavailable,
-                // which is only the case for Java < 9 (and therefore module-info.java is
-                // irrelevant).
+                // Suppress IntelliJ warning about module-info.java needing
+                // `requires jdk.unsupported` for `sun.misc.Unsafe`. This code here is only a
+                // fallback when `VarHandle::fullFence` is unavailable, which is only the case for
+                // Java < 9 (and therefore module-info.java is irrelevant).
                 @SuppressWarnings("Java9ReflectionClassVisibility")
                 Class<?> unsafeClass = Class.forName("sun.misc.Unsafe");
                 var theUnsafeField = unsafeClass.getDeclaredField("theUnsafe");
diff --git a/wasm/src/main/java/run/endive/wasm/Parser.java b/wasm/src/main/java/run/endive/wasm/Parser.java
index ce5383706..34b4182fa 100644
--- a/wasm/src/main/java/run/endive/wasm/Parser.java
+++ b/wasm/src/main/java/run/endive/wasm/Parser.java
@@ -95,6 +95,10 @@
 
 /**
  * Parser for Web Assembly binaries.
+ *
+ * <p>If parsing fails, for example due to invalid or unsupported Wasm code, an exception is thrown.
+ * In many cases that exception will be a {@link WasmEngineException} or a subclass of it, but
+ * callers should be prepared to handle any kind of {@code RuntimeException}.
  */
 @SuppressWarnings("UnnecessaryCodeBlock")
 public final class Parser {
@@ -229,18 +233,30 @@ public Parser build() {
         }
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public static WasmModule parse(InputStream input) {
         return new Parser().parse(() -> input);
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public static WasmModule parse(byte[] buffer) {
         return new Parser().parse(() -> new ByteArrayInputStream(buffer));
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public static WasmModule parse(File file) {
         return parse(file.toPath());
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public static WasmModule parse(Path path) {
         return new Parser()
                 .parse(
@@ -254,6 +270,9 @@ public static WasmModule parse(Path path) {
                         });
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public WasmModule parse(Supplier<InputStream> inputStreamSupplier) {
         WasmModule.Builder moduleBuilder = WasmModule.builder();
         moduleBuilder.withValidation(validate);
@@ -282,6 +301,9 @@ public WasmModule parse(Supplier<InputStream> inputStreamSupplier) {
         return moduleBuilder.build();
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public void parse(InputStream in, ParserListener listener) {
         parse(in, listener, true);
     }
@@ -445,10 +467,16 @@ private void parse(InputStream in, ParserListener listener, boolean decode) {
         }
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public static void parseWithoutDecoding(byte[] bytes, ParserListener listener) {
         new Parser().parseWithoutDecoding(new ByteArrayInputStream(bytes), listener);
     }
 
+    /**
+     * @throws RuntimeException if parsing fails
+     */
     public void parseWithoutDecoding(InputStream in, ParserListener listener) {
         parse(in, listener, false);
     }