[spec review] 2 - Structure

[flagxor]

Detail oriented review of draft text:
http://webassembly.github.io/spec/core/bikeshed/index.html#structure%E2%91%A0

Try to be ready to discuss issues by the next in person WG meeting.

[lukewagner]

Driveby nit:

• § 2.3.2 and § 2.3.3: I can't find anywhere in the conventions where square brackets are defined. On first glance it looks like an "Array of" constructor, but that's definitely not what it means. I think it might just be a stylistic cue that "this is a result/function type" in which case it might be good to call that out.

[dschuff]

• § 2.1.1 Many productions use the syntax "sym := \dots | A | B" to indicate adding additional cases to a previously-described production. A note about that convention could probably be added in this section.

• § 2.1.2 The rendering of replacement notation, e.g. :s \with [i \slice n] in the multipage version is a link to the correct #notation-replace anchor; however in the editor's draft it doesn't get special handling and renders more or less as swith[i] which is hard to read.

• § 2.2.4 "lengths of a name" should be "length of a name"

• § 2.4 "consuming (popping) argument values and producing (pushing) result values." This section uses "produce" and "return" fairly interchangeably when talking about result types or values of instructions. So this sentence should maybe mention that, e.g. "producing/returning (pushing) result values"

• § 2.4.1 "flavours" It looks like American spelling is used elsewhere in this document, so this should be "flavors" for consistency.

• § 2.4.2 "The drop operator simply throws away a single operand": could be more precise as something like "consumes a single operand and produces no result".

• § 2.4.3 "Variable instructions are concerned with the access to local or global variables." Drop the "the". It's cleaner.

• § 2.4.5 nop is listed with the control instructions. But it's a (non)-arithmetic instruction just as much as it's a (non)-control-flow-affecting instruction. I'd vote to put it with the parametric instructions since it takes 0 operands of any type :D

• § 2.4.5 "unlike other index spaces" I believe this is the first mention of the term "index space"; it should probably link forward to where index spaces are discussed (§ 2.5.1)

• § 2.5.1 "The index space for locals ... includes the parameters and local variables of that function, which precede the other locals." Should be something like "includes the parameters of the function, which precede the local variables"

• § 2.5.1.1 "The meta variables x,y ranges" should be "range"

• § 2.5.2 "All function types used in a module must be defined " It might be worth calling out that this includes types of imported functions?

• § 2.5.3 It might be worth calling out that function parameters are mutable too. Or just drop the statement that locals are mutable, if the purpose of this section is just to describe indexing?

• § 2.5.5 "The mems component" Given the outcome of Rename grow_memory and memory_size? #627 this component should probably be called "memories" (which I like better anyway). I believe this particular "mems" is really only reflected in parts of the abstract grammar and doesn't appear e.g. anywhere in the text format. But I guess that probably means that the mem terminal symbol in the grammar should be "memory" as well?

• § 2.5.7 "initialize a subrange of a table at a given offset from a static vector of elements." It might be better as "initialize a subrange of a table (at a given offset) from a static vector of elements." so that the association of "from" is more clear.

• § 2.5.8 "The initial contents of a memory are zero bytes." might be better as "The initial contents of a memory are zero-valued bytes" or "zero-bytes" something to indicate that zero is the value and not the count. Also, same comment as 2.5.7 wrt "offset from"

• § 2.5.9 "The start component of a module optionally declares" I think we can drop "optionally". If present the component always declares the start function index (and all components are optional).

[rossberg]

Thanks for the review! See #766.

• § 2.1.1 Many productions use the syntax "sym := \dots | A | B" to indicate adding additional cases to a previously-described production. A note about that convention could probably be added in this section.

Done.

§ 2.1.2 The rendering of replacement notation, e.g. :s \with [i \slice n] in the multipage version is a link to the correct #notation-replace anchor; however in the editor's draft it doesn't get special handling and renders more or less as swith[i] which is hard to read.

See #669, should be fixed by #765.

§ 2.2.4 "lengths of a name" should be "length of a name"

Done.

§ 2.4 "consuming (popping) argument values and producing (pushing) result values." This section uses "produce" and "return" fairly interchangeably when talking about result types or values of instructions. So this sentence should maybe mention that, e.g. "producing/returning (pushing) result values"

Done.

§ 2.4.1 "flavours" It looks like American spelling is used elsewhere in this document, so this should be "flavors" for consistency.

Done.

§ 2.4.2 "The drop operator simply throws away a single operand": could be more precise as something like "consumes a single operand and produces no result".

Well, this section is trying to focus on providing brief and intuitive explanations of the role of each instruction and avoiding distracting detail. Section 4 is where it's all made precise.

§ 2.4.3 "Variable instructions are concerned with the access to local or global variables." Drop the "the". It's cleaner.

Done.

§ 2.4.5 nop is listed with the control instructions. But it's a (non)-arithmetic instruction just as much as it's a (non)-control-flow-affecting instruction. I'd vote to put it with the parametric instructions since it takes 0 operands of any type :D

I agree that nop is placed somewhat randomly, but we have always lumped it in with the control instructions in the design docs.

§ 2.4.5 "unlike other index spaces" I believe this is the first mention of the term "index space"; it should probably link forward to where index spaces are discussed (§ 2.5.1)

Done.

§ 2.5.1 "The index space for locals ... includes the parameters and local variables of that function, which precede the other locals." Should be something like "includes the parameters of the function, which precede the local variables"

Done.

§ 2.5.1.1 "The meta variables x,y ranges" should be "range"

Done.

§ 2.5.2 "All function types used in a module must be defined " It might be worth calling out that this includes types of imported functions?

Note the difference between "function types" and "functions' types". ;) Function types occur in multiple places, e.g., including call_indirect instructions, and various others in the future. Not sure it scales to enumerate all of them here.

§ 2.5.3 It might be worth calling out that function parameters are mutable too. Or just drop the statement that locals are mutable, if the purpose of this section is just to describe indexing?

Done. (The section introduces the concept of functions, parameters and locals, so it's worth mentioning mutability.)

§ 2.5.5 "The mems component" Given the outcome of #627 this component should probably be called "memories" (which I like better anyway). I believe this particular "mems" is really only reflected in parts of the abstract grammar and doesn't appear e.g. anywhere in the text format. But I guess that probably means that the mem terminal symbol in the grammar should be "memory" as well?

The spec consistently uses "mem" for all internal naming of syntactic or semantic objects, otherwise it would become overly verbose in many places -- in the semantics, "memory" occurs far more frequently than in the concrete syntax of the language. For example, consider names like "memarg" or the formal rules in sections like 4.4.4.

§ 2.5.7 "initialize a subrange of a table at a given offset from a static vector of elements." It might be better as "initialize a subrange of a table (at a given offset) from a static vector of elements." so that the association of "from" is more clear.

Done (using comma to avoid parens).

§ 2.5.8 "The initial contents of a memory are zero bytes." might be better as "The initial contents of a memory are zero-valued bytes" or "zero-bytes" something to indicate that zero is the value and not the count. Also, same comment as 2.5.7 wrt "offset from"

Done.

§ 2.5.9 "The start component of a module optionally declares" I think we can drop "optionally". If present the component always declares the start function index (and all components are optional).

Done.

[bongjunj]

Driveby nit:

• § 2.3.2 and § 2.3.3: I can't find anywhere in the conventions where square brackets are defined. On first glance it looks like an "Array of" constructor, but that's definitely not what it means. I think it might just be a stylistic cue that "this is a result/function type" in which case it might be good to call that out.

It would be better to have this notation defined in the convention section. Is there any discussion went, or decision made in the past on this? I don't think the notation can be interpreted in many other ways, but it is somehow not helpful to a reader.

[rossberg]

@Binjune, it might have been answered at one of the in-person meetings, I don't remember. But the answer is that they are defined as part of the syntax for result types here. Note that the convention section merely defines "meta" syntax, i.e., notation to specify the actual syntax. The result brackets do not belong there, because they are part of the actual syntax being defined.

I have in fact considered dropping the brackets in the past, since they cause some clutter. But they also help clarity in some cases, especially for empty result types.

[bongjunj]

@rossberg, thank you for the reply.

As I am currently trying to study meta-syntax for how abstract syntax should be defined, I always fell back to set a special case for a square-braced of something(because it was not mentioned in the conventions).
So, at the moment, I am not convinced that the meta-syntax discussed in the conventions section can cover the square-braced cases. Do you have any thoughts on how the conventions can properly explain the case?

[rossberg]

@bonjune, not sure I understand the question. The brackets are simply a piece of concrete syntax (terminal) in the grammar, just like, say, the arrow in function types. (Granted, there is some notational overloading between concrete and meta syntax, and brackets are used on both levels, but I would hope that it is usually clear from context.)

Edit: Perhaps it would help to clarify in the conventions section that atoms can also be symbolic?