Documentation on xsCallFunction functions.

[rmontrosecbw]

Other than being listed in xs.h and appearing as used for call-backs in various code modules, is there documentation for the xsCallFunction functions? It isn't mentioned in the Moddable documentation. Searching the web, it appears there used to be an "XS Host Programming Guide" that described the functions and how they worked, but that is no longer in the Moddable documentation.

[phoddie]

Use xsCallFunction* to call a function when you have a function object. Use xsCall*, by contrast, to call a method of an object by name.

This JavaScript...

this.foo(101)

...is implemented in C using xsCall* to call the foo method of this:

xsCall1(xsThis, xsID_foo, xsInteger(101));

This JavaScript...

let foo = ...; // get the function object into "foo" as appropriate 
foo.call(this, 101);

...is implemented in C using xsCallFunction* to call the function foo with a receiver of this:

// get the function object into "xsVar(0)" as appropriate
xsCallFunction1(xsVar(0), xsThis, xsInteger(101));

[rmontrosecbw]

That makes sense, and given the usefulness of the xsCallFunction for callbacks, why isn't it documented in the XS in C section with the xsCall?

[phoddie]

Top ten reasons that the xsCallFunction* APIs aren't documented:

🔟 The intern forgot
9️⃣ Lazy maintainers
8️⃣ Waiting for them to reach Stage 3
7️⃣ Our lawyer thought they qualified as a circumvention measure under the DMCA
6️⃣ We weren't told this would be on the test
5️⃣ Some knowledge must be earned
4️⃣ We enjoy answering questions
3️⃣ It's in our backlog
2️⃣ No one here could figure out how they work
1️⃣ Hold on just a minute... they are documented!

[rmontrosecbw]

One of the best top-Ten lists! Glad it got into 5.12!

[rmontrosecbw]

Maybe add to the backlog to document the xsReference and xsToReference macros to convert from C pointers to/from a slot (I think that's what they do). We're writing our own wrappers around custom C components and run into these.