Extend typescript --emit-tsd with jsdoc

[charnley]

Just polling here before trying to extend Emscripten. I maintain a WASM NPM package, and I would love to extend the type documentation with JSDoc. Currently, the interface .d.ts. exports very nicely, but to have the full interface hosted with something like typedoc.org (similar to sphinx-doc.org for cpp), I would need to also embed documentation into the .function() interface.

Has this been considered before? I didn't see any discussion about it.

I was thinking something like.

float randomFunction(float a, float b, float c) {
    return a + b + c;
}

EMSCRIPTEN_BINDINGS(my_module) {
    function(
        "randomFunc(a,b,c)",
        &randomFunction,
        doc(
            "A Completely Random Function.\n"
            "@param a - Start value\n"
            "@param b - End value\n"
            "@param c - Another number\n"
            "@returns The sum"
        )
   );
}

producing

interface EmbindModule {
  /**
   * A Completely Random Function.
   * @param a - Start value
   * @param b - End value
   * @param t - another number
   * @returns The sum
   */
  randomFunc(a: number, b: number, t: number): number;
}

I think it would help produce nicely self-documented WASM code.

[sbc100]

@brendandahl WDYT?

[brendandahl]

It would be nice to have better TS output, but I see two potential issues with above approach. 1) We'd need to support doc for all the various binding methods e.g. class, enum, ... 2) The doc string would be embedded in the the wasm binary and I don't see an easy way to DCE it, since it will be referenced by the binding.

Another potential option (that may not need to live in emscripten) is you could extract a comment from the c++ source either specifically for that binding or from the original function and then have a script to inject it into the .d.ts e.g.

EMSCRIPTEN_BINDINGS(my_module) {
    /**
     * A Completely Random Function.
     * @param a - Start value
     * @param b - End value
     * @param c - Another number
     * @returns The sum
     */
    function("randomFunc(a,b,c)", &randomFunction);
}

[charnley]

I thought about C++ extraction. I also thought about having yaml that contains all the docstrings to inject afterwards. Both are possible but would require that I maintain a glue script as part of the package, where I would prefer to rely on a stable interface.

1. We'd need to support doc for all the various binding methods e.g. class, enum

Do you mean JSDoc syntax? My thought was to provide a string and let the author find the right JSDoc syntax. So basically just a "comment before the function"