Request: Annotations for definitions of Wasm proposals/extensions

[Robbepop]

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 <proposal_name>. 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.

[alexcrichton]

Thanks for the report and this sounds like a great idea to me! At the very least I think documentation would be good to add for proposals. Ideally it might be kind of nice to move towards a system where we use Cargo features, but I'm not sure if that can easily be done.

[Robbepop]

Glad you like the idea!

I think you are right that it would be pretty cool if crate features allowed to enable only parts of the entire Wasm spec. The best solution has compile-time configs (through mentioned crate features) as well as dynamic (as it is now via config types) ways.

However, those proposed documentation lines are still helpful in this case for what I called the "dynamic" approach that we already have.

I think it is fine to add these incrementally whenever changes to the wasmparser crate are done following the principle to leave a place better than you found it. Maybe if I find some time I will file a PR but I am not sure about so many definitions and their origins at the moment that it probably won't make too much sense.

[alexcrichton]

I think that this is done now with the for_each_operator! macro

[Robbepop]

Partially this is indeed done in the for_each_operator! macro, however, this issue was meant more widespread as a means of putting documentation hints onto any Rust definition that are specific to a Wasm proposal such as types, fields, methods etc.

[alexcrichton]

Ah ok, my mistake.