Add spec URLs for javascript.operators.spread

[sideshowbarker]

@Josh-Cena This one could really use some review and guidance from you. Of the three ES spec URLs this change adds, I’m not 100% convinced that any of them are what we need here. The first one, #prod-SpreadElement, seems like the one most likely correct — but I’m less sure about the #prod-ArgumentList one, and even less sure about the #prod-PropertyDefinition one.

In general I have only a vague understanding of the formalism that the ES spec uses, and how it translates to the syntax in JavaScript code. But I found https://stackoverflow.com/a/37152508/441757 helpful in trying to connect the dots a bit more. However, that’s also made me realize I’m not sure exactly what “spread syntax” — or more like, which spread syntaxes — our article at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax is meant to be scoped to (and thus also what we should be scoping this BCD entry to).

[Josh-Cena]

Yes—these URLs are correct. MDN is (for good reason) merging three spread syntaxes into one, but using consistent terminology within the page (i.e. we are always clear if we are talking about array spreading, parameter spreading, or object spreading).

Speaking of this, in Python the two "spread operators" are slightly different—* for arrays and ** for objects (dictionaries).

a = { "foo": 1, "bar": 2 }
b = { **a, "baz": 3 }

a = [1, 2]
b = [*a, 3]

# args is an array and kwargs is a dict
def foo(*args, **kwargs):
    pass

That IMO is clearer from a language design perspective, and maybe makes those who dislike operator overloading happy :D

[Josh-Cena]

We have three subitems here. The spread_in_function_calls one lacks a spec URL. Should we add one for that?

[sideshowbarker]

We have three subitems here. The spread_in_function_calls one lacks a spec URL. Should we add one for that?

Yes, we should. If you have the spec URL at hand, that’d be great — I can add it on this PR branch

[Josh-Cena]

Actually I think we should update the other two URLs as well! prod-SpreadElement is array spreading, prod-ArgumentList is argument spreading, and prod-PropertyDefinition is object spreading. IMO, we should replace the current #sec-array-initializer and #sec-object-initializer ones with those since those three are more specific. The three spec URLs you have added are exactly the three needed.

(Of course, every syntax-directed operation usually has two spec locations: one for the syntactical production which you found, one for the runtime semantics like https://tc39.es/ecma262/multipage/ecmascript-language-expressions.html#sec-runtime-semantics-argumentlistevaluation. Do we have a convention to include both or only the syntactical production?)

[sideshowbarker]

Actually I think we should update the other two URLs as well! prod-SpreadElement is array spreading, prod-ArgumentList is argument spreading, and prod-PropertyDefinition is object spreading. IMO, we should replace the current #sec-array-initializer and #sec-object-initializer ones with those since those three are more specific. The three spec URLs you have added are exactly the three needed.

OK, please take a look now — I pushed an update to make it as described above.

Note however that this leaves us with no spec URL for the javascript.operators.spread feature (parent item) itself. That’s normally considered a bug, because I run a linter which basically checks that every item with an mdn_url also has a spec_url. However in this case it seems that the spec itself doesn’t provide us with any section with anything about “spread syntax” in general — but instead just these specific sections we’re (now) linking to for each of the subitems.

Anyway, we have similar existing cases of that kind of thing — so my linter code has an allowlist that I can add this one to.

(Of course, every syntax-directed operation usually has two spec locations: one for the syntactical production which you found, one for the runtime semantics like tc39.es/ecma262/multipage/ecmascript-language-expressions.html#sec-runtime-semantics-argumentlistevaluation. Do we have a convention to include both or only the syntactical production?)

I think the (undocumented) convention we have effectively is that the links are to the syntactical productions, and not to the runtime semantics. I wish I could assert that more strongly, since I was actually the one who added almost all of them to BCD initially — but when I did the initial adding of them, it was based mostly on the spec URLs we had in the already been using in the existing Specifications sections in MDN articles. However, I recall doing some “normalizing” of them when I added them to BCD, and I think in part that might have involved choosing the productions rather than the runtime stuff.

Regardless, considering it right now in terms of the developer audience we’re optimizing for in MDN — rather than the audience of runtime implementors or others — it seems like using the productions makes the most sense.

That said, though, nothing about this is written in stone — so if you think we should be linking to the runtime semantics instead, we should discuss it more, and we could make changes. (It’d be a lot of changes of course — but if we ended up deciding that’s how we wanted to do it, it seems like we might be able to automate much of the changes, since the ES spec anchors follow a consistent pattern.)

[Josh-Cena]

I don't have strong feelings. If you ask me then linking to runtime semantics is my call—since the behavior is usually more interesting than the syntax (which should hopefully be straightforward!) Also, it's relatively easier to jump from runtime semantics to the corresponding production than the other way round (I would consider that a defect of ecmarkup itself, though). I've constantly finding myself scrolling through pages just to get to the runtime semantics of a certain production (especially in the expressions section) since they are not closely collocated. But to tell you the truth, I don't think there's a consistent pattern to do the prod => sec conversion so AFAICT it has to be mostly manual. As of now, for the sake of consistency, I would go with the syntax production.

[queengooborg]

LGTM, I trust your judgement for spec URLs, @sideshowbarker, and yours on JavaScript, @Josh-Cena!