Additional internal docs in the wasm utilities.

FossilOrigin-Name: 5a2245a9ebae6d23cd343e46b9d730f66ec4d5ffc91b83ed11a0fbd2194ad807

1 files changed, 25 insertions, 3 deletions

diff --git a/ext/wasm/common/whwasmutil.js b/ext/wasm/common/whwasmutil.js
index 0437ef35d..65421e3fa 100644
--- a/ext/wasm/common/whwasmutil.js
+++ b/ext/wasm/common/whwasmutil.js
@@ -1382,15 +1382,19 @@ globalThis.WhWasmUtilInstaller = function(target){
      conversion of argument or return types, but see xWrap() and
      xCallWrapped() for variants which do.
 
+     If the first argument is a function is is assumed to be
+     a WASM-bound function and is used as-is instead of looking up
+     the function via xGet().
+
      As a special case, if passed only 1 argument after the name and
      that argument in an Array, that array's entries become the
      function arguments. (This is not an ambiguous case because it's
      not legal to pass an Array object to a WASM function.)
   */
   target.xCall = function(fname, ...args){
-    const f = target.xGet(fname);
+    const f = (fname instanceof Function) ? fname : target.xGet(fname);
     if(!(f instanceof Function)) toss("Exported symbol",fname,"is not a function.");
-    if(f.length!==args.length) __argcMismatch(fname,f.length)
+    if(f.length!==args.length) __argcMismatch(((f===fname) ? f.name : fname),f.length)
     /* This is arguably over-pedantic but we want to help clients keep
        from shooting themselves in the foot when calling C APIs. */;
     return (2===arguments.length && Array.isArray(arguments[1]))
@@ -1537,7 +1541,7 @@ globalThis.WhWasmUtilInstaller = function(target){
        jsFuncToWasm().
 
      - bindScope (string): one of ('transient', 'context',
-       'singleton'). Bind scopes are:
+       'singleton', 'permanent'). Bind scopes are:
 
        - 'transient': it will convert JS functions to WASM only for
          the duration of the xWrap()'d function call, using
@@ -1787,11 +1791,29 @@ globalThis.WhWasmUtilInstaller = function(target){
   const __xResultAdapterCheck =
         (t)=>xResult.get(t) || toss("Result adapter not found:",t);
 
+  /**
+     Fetches the xWrap() argument adapter mapped to t, calls it,
+     passing in all remaining arguments, and returns the result.
+     Throws if t is not mapped to an argument converter.
+  */
   cache.xWrap.convertArg = (t,...args)=>__xArgAdapterCheck(t)(...args);
+  /**
+     Identical to convertArg() except that it does not perform
+     an is-defined check on the mapping to t before invoking it.
+  */
   cache.xWrap.convertArgNoCheck = (t,...args)=>xArg.get(t)(...args);
 
+  /**
+     Fetches the xWrap() result adapter mapped to t, calls it, passing
+     it v, and returns the result.  Throws if t is not mapped to an
+     argument converter.
+  */
   cache.xWrap.convertResult =
     (t,v)=>(null===t ? v : (t ? __xResultAdapterCheck(t)(v) : undefined));
+  /**
+     Identical to convertResult() except that it does not perform an
+     is-defined check on the mapping to t before invoking it.
+  */
   cache.xWrap.convertResultNoCheck =
     (t,v)=>(null===t ? v : (t ? xResult.get(t)(v) : undefined));