What other users are doing for documenting their goja bindings?

[ganigeorgiev]

I'm currently experimenting with adding more extended goja support to one of my open source projects.
So far everything is great and works almost right out of the box without too much extra manual bindings.

My only problem is that I'm not sure how to document the Go->JS apis.

My general idea was to provide ambient TS declarations (aka. .d.ts) and allow users to import them (eg. manually with a /// <reference path="types.d.ts" /> comment, inside their tsconfig or eventually import it from the DefinitelyTyped repo).
This in theory should work fine and would also allow easy generating html docs from the .d.ts file(s), but the problem is that it is a lot of manual work.

Before investing too much time in an attempt to automate it, I wanted to check how other users are dealing with documenting their goja apis (especially when the binded go struct/func references/returns some 3rd-party package struct/func).

I checked k6 for an example and it has great html documentation and TS declarations, but at first glance they don't seem to be autogenerated.

[ganigeorgiev]

After experimenting with several different approaches (unfortunately calling gopls and godoc programmatically ended up very cumbersome and I abandoned it), I created a small helper package to semi-automate the process - tygoja (it relies on go/packages for loading and analyzing the packages).

It's far from perfect, but for now this approach seems to work fine, at least for my use case.

The final code intellisense result looks like this:

In the above $app is a plain core.App value binding via vm.Set("$app", app).
The declarations for the core.App interface and the echo router fields and methods are generated automatically by recursively parsing each field, method, argument and return type from the github.com/pocketbase/pocketbase/core package.

The general idea is that you map your exposed goja APIs against the generated package typings to inherit their documentation and fields, something like:

declare var $app: core.App // core.App is auto generated namespaced interface

For custom constructors it is a slightly more complicated as it will depend on what arguments your constructor accept.
For example, the following goja constructor:

vm.Set("Route", func(call goja.ConstructorCall) *goja.Object {
    instance := &echo.Route{}

    if data := call.Argument(0).Export(); data != nil {
        if raw, err := json.Marshal(data); err == nil {
            json.Unmarshal(raw, instance)
        }
    }

    instanceValue := vm.ToValue(instance).(*goja.Object)
    instanceValue.SetPrototype(call.This.Prototype())

    return instanceValue
})

Is manually declared as:

interface Route extends echo.Route{} // merge with the autogenerated type
declare class Route implements echo.Route {
  constructor(data?: Partial<echo.Route>)
}

For generating HTML docs, I plan to use typedoc by feeding it the generated .d.ts file.
With the default theme it looks like this (you can create your own them or use the JSON output for a more customized visualization):

My current docs integration code could be found in the develop branch of the PocketBase jsvm plugin (the goja integration is not done yet as it is missing a http client helper and some other minor adjustments and unit tests; once finalized it will be part of PocketBase v0.17.0).

I hope this helps. I'm still open for other suggestions if anyone has a better idea how to improve the above flow.