Include a wasm section for documentation of exported interfaces.

[lachlansneff]

I think it'd be useful for wasm modules to optionally include their own documentation of their exported api.

For example, there could be a command line application compiled to wasm that uses interface types to receive rich input from the user. The shell, presumably designed specifically for wasm applications, could give the user hints as to what they're allowed to input, as well as what a specific parameter, record field, or whatnot means.

[lukewagner]

Documentation of exports makes a lot of sense, but I wonder if this is best considered as a new kind of custom section defined in the tool conventions?

[lachlansneff]

Sure, it would make sense as a tool convention. What I’m imagining would be interface type specific though, since documentation would be tied to parameters, fields of parameters, etc.

[jgravelle-google]

You're thinking of an IntelliSense-like interface? First off, I think that would be cool as heck. I think that type imports would do a great job of constraining legal parameters on its own. Record types also would give a lot of information on how a function expects to be called.

This doesn't preclude documentation though. And I agree with @lukewagner that it makes sense as a custom section that the shell can interpret. The documentation section can still use indices to refer to params/fields/functions in the interface types section. The names section is an example of a custom section that indexes into other sections. Similarly, the [relocation section] described in the tool-conventions repo indexes into a bunch of other sections.

From both a simplicity of the spec and a separation of concerns perspective, it makes sense to factor documentation out to its own section in a similar vein.

[lachlansneff]

Yeah, in that vein of things :)

I'll go and make an issue on the tool conventions about this.