> Back to the original goal of this post. While I enjoy writing WAT code, one aspect of the experience that could be improved is documentation. The WASM spec is much more suitable for formal verification than for actual documentation purposes; specifically, it's hard to grep and doesn't provide much in terms of examples. This is alright for a spec, but I couldn't find complementary resources that just show code samples.
I know the pain. One time, I was trying to use an experimental academic research tool. The tool accepts an input file, written in a custom language. The language is fully documented, but the only thing the documentation did was listing the syntax of each command in BNF notation. But at least it had demo code in the repo so you could read code and doc side by side to figure out how the code should look like...
At one point I hand-wrote a simple Brainfuck interpreter in both WAT (called WAST at the time...) and asm.js. Both are extremely tedious, but it seems WAT has improved a bit ergonomically since...
This is fantastic. The specs and the MDN documentation are pretty detailed, but I’ve found I need a fair bit of trial and error to understand some WAT language features.
The loop with a block directly inside is a good regular pattern! I’ll be using that all the time now.
I’ve been writing an Elixir DSL for WAT. Elixir has a powerful macro system, so I can closer to that pseudo C-syntax in this post, plus some other niceties. I plan to open source it as a library soon.
Here are examples I’ve written in it, like an HTML escaper, stateful HTML component, bump allocator, and a few state machines.
This is awesome, as it helps Wasm newcomers to overcome the chasm and see what everything is all about with simple examples (although I wished it was a bit more extended!).
It's also very true that overall the Wasm docs can use some help. Hopefully we will be able to help with it as part of our work in Wasmer :)
I know the pain. One time, I was trying to use an experimental academic research tool. The tool accepts an input file, written in a custom language. The language is fully documented, but the only thing the documentation did was listing the syntax of each command in BNF notation. But at least it had demo code in the repo so you could read code and doc side by side to figure out how the code should look like...