Small fixes/updates to README.md, pre.js and shell.html

README.md

@@ -4,9 +4,9 @@ A project to bring the [SANE API](http://www.sane-project.org/intro.html) to the
 
 Currently, it only supports USB scanners and is only tested on a browser environment (WebUSB).
 
-This works by compiling all SANE backends (and required dependencies) to WebAssembly using Emscripten. The other key piece is @RReverser's [bridge from libusb to WebUSB](https://github.com/libusb/libusb/pull/1057) ([1](https://web.dev/porting-libusb-to-webusb/)/[2](https://web.dev/porting-gphoto2-to-the-web/)) with [some patching](deps/libusb.patch) to support multi-threading.
+This works by compiling all SANE backends (and required dependencies) to WebAssembly using Emscripten. The other key piece is @RReverser's [bridge from libusb to WebUSB](https://github.com/libusb/libusb/pull/1057) ([1](https://web.dev/porting-libusb-to-webusb/)/[2](https://web.dev/porting-gphoto2-to-the-web/)) with [some patching](https://github.com/goncalomb/sane-wasm/issues/1) to support multi-threading.
 
-Right now, it includes [all backends](http://www.sane-project.org/lists/sane-backends-cvs.html) that have support for at least one USB device (genesys is not included due to issues). No [external backends](http://www.sane-project.org/lists/sane-backends-external.html) are included at the moment.
+Right now, it includes [all backends](http://www.sane-project.org/lists/sane-backends-cvs.html) that have support for at least one USB device ([genesys is not included due to issues](https://github.com/goncalomb/sane-wasm/issues/3)). No [external backends](http://www.sane-project.org/lists/sane-backends-external.html) are included at the moment.
 
 ## WebScan
 
@@ -15,7 +15,7 @@ Right now, it includes [all backends](http://www.sane-project.org/lists/sane-bac
 If you are interested in seeing the compiled output of sane-wasm, check:
 
 * [webscan.goncalomb.com/sane-wasm/](https://webscan.goncalomb.com/sane-wasm/): all files
-* [webscan.goncalomb.com/sane-wasm/libsane.html](https://webscan.goncalomb.com/sane-wasm/): test page
+* [webscan.goncalomb.com/sane-wasm/libsane.html](https://webscan.goncalomb.com/sane-wasm/libsane.html): test page
 
 ## Building
 
@@ -140,4 +140,4 @@ _documentation in progress, the API may still suffer changes_
 
 ## License
 
-Because of the weird state of SANE's licensing (GPL + linking exception, on some backends), see [backends/LICENSE](https://gitlab.com/sane-project/backends/-/blob/master/LICENSE). I releasing this project with dual licensing [GNU GPLv2](LICENSE.txt) + [GNU LGPLv2.1](LICENSE-LGPL.txt). IANAL, you choose.
+Because of the weird state of SANE's licensing (GPL + linking exception, on some backends), see [backends/LICENSE](https://gitlab.com/sane-project/backends/-/blob/master/LICENSE). I'm releasing this project with dual licensing [GNU GPLv2](LICENSE.txt) + [GNU LGPLv2.1](LICENSE-LGPL.txt). IANAL, you choose.

pre.js

@@ -55,6 +55,22 @@
     }
     EnumSANE.reverseObject = Symbol("reverseObject");
 
+    // Many SANE functions are expected to return a promise, even though
+    // they originally are blocking calls. This happens because we use
+    // emscripten's asyncify feature.
+    // https://emscripten.org/docs/porting/asyncify.html
+    // So calls that would block (because they call sleep, access libusb, wait
+    // for web apis, etc.) just return a promise.
+    // A call only returns a promise if it falls in one of those cases that
+    // triggers asyncify.
+    // To normalize the API, we wrap SANE functions that have change to be
+    // async in a promise (to make sure they always return a promise).
+    // We call that promisify.
+    // Because of the complex code path of all SANE backends, and the use of
+    // indirect calls, it's not known if all SANE functions need to be wrapped.
+    // XXX: If any new functions are found to possibly return a promise,
+    //      add them to the list. THIS WILL CAUSE THE PUBLIC API TO CHANGE.
+
     const libFunctionsAsync = { // true = promise return is expected
         sane_get_state: false, // sync, implemented in glue.cpp
         sane_init: false, // sync?
@@ -108,15 +124,17 @@
     // The library just starts working when we call sane_init externally.
 
     Module.postRun.push(() => {
+        // promote enums to more useful objects
         ["SANE_STATUS", "SANE_TYPE", "SANE_UNIT", "SANE_CONSTRAINT", "SANE_FRAME"].forEach(s => {
             EnumSANE.promote(Module[s]);
         });
 
+        // set test backend number of devices
         if (Module.sane.debugTestDevices) {
             let buf = Module.FS.readFile("/etc/sane.d/test.conf");
             let match = false;
             const arr = (new TextDecoder()).decode(buf).split("\n").map(l => {
-                if (l.match(/^\s*number_o_devices\s+.*$/)) {
+                if (l.match(/^\s*number_of_devices\s+.*$/)) {
                     match = true;
                     return `number_of_devices ${Module.sane.debugTestDevices}`;
                 }
@@ -129,6 +147,7 @@
             Module.FS.writeFile("/etc/sane.d/test.conf", buf);
         }
 
+        // enable debug for sane function calls
         if (Module.sane.debugFunctionCalls) {
             const wrap = (fn) => (...args) => {
                 const res = fn(...args);
@@ -143,6 +162,7 @@
             });
         }
 
+        // wrap sane functions with promises to normalize api
         if (Module.sane.promisify) {
             const wrap = (fn) => (...args) => {
                 const res = fn(...args);
@@ -153,6 +173,8 @@
             });
         }
 
+        // wrap sane functions using promise queue to prevent further calls
+        // while other async functions are still running (not supported)
         if (Module.sane.promisify && Module.sane.promisifyQueue) {
             const queue = [];
             let busy = false;

shell.html

@@ -1,4 +1,9 @@
 <!DOCTYPE html>
+<!--
+    SANE WebAssembly (sane-wasm)
+    Copyright (C) 2023 Gonçalo MB <me@goncalomb.com>
+    GNU GPLv2 + GNU LGPLv2.1
+-->
 <html lang="en">
     <head>
         <meta charset="utf-8">
@@ -21,6 +26,14 @@ <h1>Test Page for SANE WebAssembly (sane-wasm)</h1>
             <p>This project (sane-wasm) is a WebAssembly port of the <a href="http://sane-project.org/">SANE API</a> for in-browser scanning (USB scanners).</p>
         </header>
         <main>
+            <ul>
+                <li><strong>This is a test page.</strong> It's not designed for final image acquisition.</li>
+                <li>This project uses some of the latest web features, a modern browser is required.</li>
+                <li>Using this page requires understanding the <a href="https://sane-project.gitlab.io/standard/api.html#code-flow">SANE Code Flow</a> and the overall SANE library.</li>
+                <li>If you reload/leave the page without clearing the scanner state (e.g. closing the page while scanning) you might need to reset the device (i.e. reconnecting).</li>
+                <li>There are some safeguards in place, but it might still be possible to lock the browser window or the scanner.</li>
+                <li>Check the console for useful information.</li>
+            </ul>
             <h2>Device Pairing (WebUSB)</h2>
             <p>
                 <button id="btn-request-device">navigator.usb.requestDevice()</button>