Any API documentation or reference?

[ghost]

Prior to anything thanks for your efforts on making this project, it's really interesting and I'm creating an application with it. But there is no documentation right now for this project (or at least I can't find it). I understand that it all uses the Spider-monkey's API but things are different when it comes to using your wrapper library. I've already reverse engineered some of your wrapper functions but having a set of documentation pages would be awesome.

Thanks in advance.

[mic159]

When attempting to use this library, I found it helpful to look at jsjs-wrapper.js, in particular how it builds up the window (InitWindow) and document (InitDocument) objects, and learn from there. Of course, there is always the examples folder, but they are mostly quite complex (many levels of callbacks is hard to read without understanding the API first).

I think some doc comments would also help a lot, as well as some documentation pages.

[ghost]

@mic159 never noticed InitDocument! thanks for that. but it's interesting comparing this very wrapper API function with the twitter example where the programmer of twitter example created an artificial document by this piece of code:

var jsDocumentClass = JSJS.CreateClass(
    JSJS['JSCLASS_GLOBAL_FLAGS'],
    JSJS['PropertyStub'],
    JSJS['PropertyStub'],
    JSJS.wrapGetter(
        documentGetProperty,
        JSJS.Types.bool
    ),
    JSJS['StrictPropertyStub'],
    JSJS['EnumerateStub'],
    JSJS.wrapResolver(documentResolveProperty),
    JSJS['ConvertStub'],
    JSJS['FinalizeStub']
);
var jsDocument = JSJS.DefineObject(
    jsObjs.cx,
    jsObjs.glob,
    "document",
    jsDocumentClass,
    0,
    0
);

instead of simply calling InitDocument. I'm wondering why.

[jterrace]

Since the js.js API closely follows SpiderMonkey's JSAPI, a good starting point is to read this document to wrap your head around how the sandbox is interacted with: https://developer.mozilla.org/en-US/docs/SpiderMonkey/JSAPI_User_Guide

Indeed, jsjs-wrapper.js is the place to start. I think it would be useful to put some jsdoc comments in there so we could autogenerate comments, but I haven't had time to do that yet (pull requests always welcome).

The confusion with InitDocument is that it should be deprecated. We originally created InitDocument and InitWindow thinking it would be easier for users, but I don't think we got the API quite right for it, and it ended up not exposing enough to the user to be that useful.

Going forward, I think the right approach is the API they made for TreeHouse (http://www.cs.utexas.edu/~mwalfish/papers/treehouse-atc12.pdf). It looks like it makes it really easy to use. I think we could copy the same kind of API for js.js which would make it much easier to use instead of the low-level API.