Reorganize the Canonical Built-ins section. #407
Conversation
Reorganize the "Canonical Built-ins" section of Explainer.md. - Don't quote the `canon` ebpf here, as it doesn't have a lot of explanatory information. - Put builtins in their own subsections. - Give builtins synopsis tables that include their conceptual signatures, binary encoding immediates, and canonical ABI signatures. - Revise documentation to separate the conceptual signatures and semantics from the Canonical ABI representations.
| | Synopsis | | | ||
| | -------------------------- | ------------------------- | | ||
| | Conceptual signature | `func<T>(repr: ...) -> T` | | ||
| | Binary encoding immediates | `T:<typeidx>` | | ||
| | Canonical ABI signature | `[repr:i32] -> [i32]` | |
There was a problem hiding this comment.
Skimming through them, the 'Conceptual signature' row doesn't seem to add much value over the 'Canonical ABI Signature' row and sortof adds a bit of its own confusion, since it has '...' and its own custom syntax which one now has to extrapolate from. Independently, I think the 'Binary encoding immediates' are a bit out of place, since if you're implementing a binary decoder and interested in this information, you're going to need to read Binary.md anyways to see where and how the immediates are embedded in the overall definition. Thus, I think we should replace the 3-row table in each of these sub-headings with a single triple-backtick code block that contains only the Canonical ABI Signature.
Separately, I see the EBNF for resource.new and all the other built-ins is removed above, so I think we should introduce these productions in each of these subsections for reference. So, combined with the above, maybe an example for resource.new could look like:
"""
The syntax for the resource.new built-in is:
canon ::= ...
| (canon resource.new <typeidx> (core func <id>?))
the Core WebAssembly signature for this built-in defined by the Canonical ABI is:
[repr:i32] -> [handleidx:i32]
... prose describing both together ...
"""
| `T`) with `repr` as its representation and returning the a new | ||
| handle pointing to this resource. |
There was a problem hiding this comment.
| `T`) with `repr` as its representation and returning the a new | |
| handle pointing to this resource. | |
| `T`) with `repr` as its representation and returning the index of a new handle | |
| in a per-resource-type-per-component-instance table that points to a resource | |
| that contains `repr`. |
|
I'll close this for now, work on incorporating your feedback, and submit a new PR on the main branch once the stream/future PR is merged. |
This moves the signatures for the canonical builtins out of prose paragraphs and into tables, which highlights them and simplifies the prose. This also adds "conceptual signatures". The canonical ABI signatures are useful when one is writing compilers or bindings generators or other tools, while the conceptual signatures are useful for people seeking to understand what these builtins do at a conceptual level, before thinking about how all the various values are lowered into `i32`s. And, the conceptual signatures in theory are independent of the ABI, so they could be reused when new ABIs are added. This is a follow-up to WebAssembly#407; I've re-added the `canon` ebpf for now, removed the "Binary encoding immediates" table rows, and tidied up the signatures to avoid using `...`.
This moves the signatures for the canonical builtins out of prose paragraphs and into tables, which highlights them and simplifies the prose. This also adds "conceptual signatures". The canonical ABI signatures are useful when one is writing compilers or bindings generators or other tools, while the conceptual signatures are useful for people seeking to understand what these builtins do at a conceptual level, before thinking about how all the various values are lowered into `i32`s. And, the conceptual signatures in theory are independent of the ABI, so they could be reused when new ABIs are added. This is a follow-up to WebAssembly#407; I've re-added the `canon` ebpf for now, removed the "Binary encoding immediates" table rows, and tidied up the signatures to avoid using `...`.
Reorganize the "Canonical Built-ins" section of Explainer.md.
canonebpf here, as it doesn't have a lot of explanatory information.I started out with a table in Async.md, but as I worked it ended up seeming to make sense to just evolve the content in Explainer.md. I'm curious what you think!