Document Parser and Instance exception behavior

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();

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");

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);
     }