multi-value: fixes compilation errors in examples

[codefromthecrypt]

This fixes compilation errors in examples. It also changes case format of phis to PHIs so that people don't first wonder if they are reading a typo.

[codefromthecrypt]

I took this code from some existing examples in this org, and it compiles with wabt, but I want to verify it actually works

[rossberg]

Thanks. I'm fine with this, though in general, the design docs under proposals/ are historic, so they naturally might be out of date. I think there is no expectation that we keep them updated.

[rossberg]

"phi" is a greek letter, not an acronym, so this should remain lowercase.

[codefromthecrypt]

okie

[codefromthecrypt]

the design docs under proposals/ are historic, so they naturally might be out of date. I think there is no expectation that we keep them updated.

Not trying to be fussy, but I did need to look at this to figure out what this feature needs. Is there an authoritative way to get the same content? https://webassembly.github.io/spec/core/bikeshed/#multiple-values%E2%91%A0 has very little content and also links here..

[codefromthecrypt]

FWIW to implement this feature, the essential things I needed were to read this proposal which gave more detail about the general expectations. To actually do the work was reading the commit diff.

The summary at the bottom of the spec was helpful but not really for implementation. For implementation, at least for me, it is this doc and the commit that changed the spec tests because spec tests are not grouped by feature otherwise.

[codefromthecrypt]

also note to any future reader that there's typically an assumption of LLVM experience when looking at specs here. one shortcut is when in doubt about something search LLVM (that something), ex to get to the phi instruction which the "phi" here is about https://llvm.org/docs/LangRef.html#phi-instruction

[rossberg]

Thanks!

To clarify, phi nodes are part of SSA representation, so relatively generic compiler tech, nothing specific to LLVM (I have very little knowledge of LLVM myself :) ).

[codefromthecrypt]

The main point is that this spec shouldn't have prerequisites on both knowing jargon and also knowing what scope the jargon is in.

It would kill no one to say "phi nodes (in SSA representation)"

saying "phis" is basically suggesting everyone whose implementing this can jump to that context by looking at factorial code. That's an unnecessary narrowing.

We can't change the past, but I really hope we can at least recognize that having a review by someone with less experience can help with accessibility of the spec. I don't think the goal of this spec is everyone basically depending on one impl, and to change that, where the spec is highly reused, things like this help.

I'm an end user and it is places like this, where I feel there's basically some secret club who know what all the background needed is, as things are almost intentionally terse. Great example is using word like phis as if it were a normal programming term, to describe factorial!

[codefromthecrypt]

added a commit you can feel free to have me revert it, but would have saved what I feel was unnecessary jump to wondering if a sentence in front of code that says "phis" might have meant "this"

---

This also adds the context necessary (SSA) that makes learning why this is important possible for someone who doesn't already know why. Remember there are a lot of different types of engineers who can help on code around WebAssembly.

Also, the text format is used for things besides implementing compilers. People are using it for "user defined functions", general purpose code written in the text format that's intent is higher level. This doesn't negate the value in implementing things with a lot of context, but it does say that there is value being decoupled also. I've had to personally reverse document a lot of things because there are norms like no comments in spec tests, which assume people reading know tons. Anyway I feel the last commit is more empathetic even if it has some grammatical glitches as it moves from someone thinking why am I too dumb to know what "phi" is to, oh. that's what phi is! because if you try to search "phi" on its own good luck, "phis" is worse.

PS I hesitated from making a link on SSA, as I noticed web links aren't really used except to refer to GitHub. However, if this were my codebase I would (and do) when using jargon as that saves the search engine step.

[rossberg]

Well, this isn't the spec document, but a historic design doc. It is preserved in the repo to document and reflect the original discussion. Perhaps the README should have a disclaimer clarifying that.

I understand your intention, but I'm not sure I'm comfortable changing these docs beyond fixing simple typos/syntax, good intentions notwithstanding. That would have a touch of "rewriting history".

[codefromthecrypt]

ok I'll kill the last commit, thanks for listening

[rossberg]

Thanks!