Use formal wit syntax within doc?

[peter-jerry-ye]

I noticed that for explaning event in explainer, it is written as:

variant event {
    none,
    subtask(subtask-index, subtask-state),
    stream-read(stream-index, stream-result),
    stream-write(stream-index, stream-result),
    future-read(future-index, future-read-result),
    future-write(future-index, future-write-result),
    task-cancelled,
}

However, per cm ast, it says:

defvaltype    ::= bool
                | s8 | u8 | s16 | u16 | s32 | u32 | s64 | u64
                | f32 | f64
                | char | string
                | error-context 📝
                | (record (field "<label>" <valtype>)+)
                | (variant (case "<label>" <valtype>?)+)

Although I assume the event is never lowered / lifted in the same way as variants (the code is returned directly and the data are picked up from the memory, or passed as arguments in callback style), is it possible that we use some consistent way to describe it, or relax the restriction on variant?

[lukewagner]

Hi, thanks for the question! Is the problem you're getting at the fact that the the built-ins using event don't literally use the Canonical ABI for returning a variant (which would not return the code as a return value but, instead, returning everything via outparam pointer)? That is true, and this is why we always say "Approximate WIT signature" in these descriptions (the idea being that we're trying to lean on WIT to convey the higher-level semantics, even if the ABI doesn't precisely link up). That being said, we're talking about switching to take advantage of core wasm multi-value return soon, and in that case the CABI may end up exactly lining up with the WIT in this case.