bytecodealliance / bytecodealliance/wasm-tools
Request: Annotations for definitions of Wasm proposals/extensions
- Dominant language
- Rust
- Stars
- 1.8k
- Forks
- 351
- Avg merge
- 16h 57m
- Merged PRs (30d)
- 38
Description
## tl;dr
We might have a discoverability problem with all the Wasm proposals and extensions implemented in this crate.
## Problem
When working with the very low level and generic `wasmparser` crate I often run into the same problem over and over again:
The `wasmparser` crate provides support not only for the WebAssembly MVP but also for many of the proposals and extensions that are finished or even under development.
For me as a person that does not have the entire set of proposals and extensions in my head it sometimes can be hard to infer what `enum` variant data structure, routine or even some fields are actually interesting for me and my projects that only supports a defined subset of the entire set of proposals and extensions of even just the MVP. As of today using the `wasmparser` often makes me feel that I have to know in advance all these proposals and how they extend the MVP set of definitions so that I can successfully filter out what I do not need and eventually provide useful information to the user for why something is (currently) not supported in my project.
## Symptoms
My current solution when I find some Wasm definitions that are unknown to me is to google for them (with mostly not so much success) followed by a query through the entire set of proposals and extensions for Wasm which can becomes very frustrating quickly if it isn't very obvious sometimes where some definitions could potentially come from. Also not very productive although I have to admit that you learn a lot in the process, however, not very helpful if you want to progress with your project.
## Solution
What would help me?
This is actually pretty simple: Each and every field, parameter, data type or enum variant that is the result of some non Wasm MVP proposal or extension needs to have one line of documentation that states which proposals or extensions imply its existence. This is all information I need to be able to do some further research and be able to easily identify parts that I do or do not need to support in case I do not know about all the proposals and all of their details that might even be under active development.
## Example
If for every such definitions there was a line of documentation that states something like `This definition is part of the Wasm proposal `. E.g. `This definition is part of the Wasm proposal for bulk memory operations.`. This allows a user of the library to then simply query this particular spec and directly find out all the details or immediate decide if this definitions is actually useful for the project at hand.
## Why `wasmparser` ?
Now the obvious question is: Why should we add this to `wasmparser`? This might be interesting for literally all low level Wasm libraries which would be way too much work. The `wasmparser` crate is just the natural entry point into Wasm and therefore suited very well for an initial implementation of these docs.
I think those documentation strings are not hard to maintain since once a proposal is finished they won't be changing a lot anymore.
## Implementation
I am sure we can incrementally get there. But what this issue demands is that in the future for everything we add to `wasmparser` we have this one line of documentation and eventually update the already existing parts to include it.
Contributor guide
Assessment
This issue has not been assessed yet.