Documentation Section

[lachlansneff]

I propose that a custom section be defined that supplied documentation of the exported api at various levels of specificity. For example, there could be module-level documentation, function-level, parameter-level, type-level, etc.

I think it should directly interface with the interface types proposal (when available, the section can be usable before then) to have the ability to document, for example, individual fields of record parameters, or individual variants of variant parameters.

The goal is to enable support for IntelliSense-like support when programming against a wasm module's api.

I'll make a pr with some initial thoughts on this in a week or so if people think this is a good idea.

I originally made an issue on the interface-types repo (https://github.com/WebAssembly/interface-types/issues/110), but it was suggested that the issue be raised here instead since it would be a tool-convention not a standardized feature.

[tlively]

I think this is a great idea, but I would definitely want to some tools use such a feature before merging documentation on it into the tool-conventions repo. We want to avoid standardizing things without real world experience with them. Do you know of any tools we could partner with in designing a documentation section?

[lachlansneff]

Not that I know of, though it would be cool to have tools like wasm-bindgen integrate with it.

Maybe there could be an experimental folder where we can try out proposals and iron out the bugs?

[tlively]

I think opening a PR for iteration would be appropriate while we figure out where we can implement the design.

[lachlansneff]

Sounds good, I'll do that! :)

[tschneidereit]

FWIW, we plan on doing something like this for the Rust toolchain. I don't think we have a firm timeline for it, though.