Docs: ... is not an operator

[fkling]

What is the purpose of this pull request? (put an "X" next to item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofixing to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

The ... in function call syntax is not an operator. It's more of a punctuation supported in various places (function call, function definition, array/object definitions, destructuring syntax), but specific to those. It does not produce a value like actual operators do.

I'd appreciate it if we can avoid spreading (no pun intended) this misconception.

Is there anything you'd like reviewers to focus on?

While "spread argument" isn't an official term either, there is none (https://www.ecma-international.org/ecma-262/9.0/index.html#sec-argument-lists), it's probably the closest reasonable term.

There might also be other pages that use this term which need to be updated.

Happy for alternative suggestions though, or to hear the reasons why this shouldn't be corrected.

[jsf-clabot]

All committers have signed the CLA.

[fatcerberus]

The ECMAScript specification itself uses the term "spread operator", admittedly only once in the preamble but that seems to be enough to indicate that "spread operator" is already an accepted term for the ... token:

This specification, the 9th edition, introduces support for asynchronous iteration via the AsyncIterator protocol and async generators. This specification also includes four new regular expression features: the dotAll flag, named capture groups, Unicode property escapes, and look-behind assertions. It also includes rest parameter and spread operator support for object properties. There have also been many minor updates, editorial and normative, with many contributions from our awesome community.

Emphasis mine.

[fkling]

That's a fair point (but makes me sad). I still want to point out that this term does not appear in previous editions.

[not-an-aardvark]

How about "spread element" instead of "spread argument"? That's the term used by ESTree.

I think an "argument" would typically refer to something passed into a function, which doesn't apply when using a spread in an array. An "element" would more generally refer to some member of a list (where the list could either be a function's arguments, an array's contents or an object's properties).

[fatcerberus]

If we really want to be neutral on this point, I suppose we could replace all instances of "the spread operator" in documentation with "spread syntax".

That said, I do still view it as an operator--it's just kind of the inverse of normal operators, i.e. instead of taking multiple values and returning a single result, it takes a single value as input and outputs a list of values. This is then naturally only valid in contexts where "list of values" makes sense, e.g. argument lists, array literals, etc.

[fkling]

@not-an-aardvark: The changes here are specifically for the call syntax, hence "argument". If it were in the context of an array literal then it should be spread element, yes.

[not-an-aardvark]

Ok, these changes look fine to me then. I'll leave this open for a little bit in case any other team members have thoughts.

[fkling]

@fatcerberus

I'd be happy with spread syntax as well (since that is used in a bunch of other places and could be used consistently in all of eslint's documentation).

That said, I do still view it as an operator--it's just kind of the inverse of normal operators, i.e. instead of taking multiple values and returning a single result, it takes a single value as input and outputs a list of values. This is then naturally only valid in contexts where "list of values" makes sense, e.g. argument lists, array literals, etc.

I like that thinking, but I guess even then people would understand "list of values" differently. An array is also a list of values to some degree, so why shouldn't I be able to do foo = ...bar then (i.e. it creates an array for me).

Or what about the comma operator? It could also be considered a list of values to some degree. Why can I not do foo = x, y, ...bar then (even though it makes no sense).

[fatcerberus]

I like that thinking, but I guess even then people would understand "list of values" differently. An array is also a list of values to some degree, so why shouldn't I be able to do foo = ...bar then.

"List of values" at the language level, not speaking of runtime semantics. foo = ...bar doesn't make sense because there's only one assignment target, where would the additional values produced by the spread go?

An array isn't itself a list of values, it merely encapsulates one. But to be fair, that's a distinction only compiler writers will really care about, so I see your point, too. Hard to say what's best for documentation, but personally, if someone says "spread operator" I will know exactly what they mean.

[fatcerberus]

As for the comma operator: It needs to die in a fire 🔥 😛

[fkling]

@fatcerberus

How about var x, y, z = ...bar then? 😉 But anyways, I get you.

[fatcerberus]

I know you're just busting my chops but that case is actually interesting. I almost expect that to work--until I realize the runtime doesn't know for sure the spread will always produce 3 values. Since it doesn't know that (and there's no way to assert it at the language level--i.e. no native tuples), the only sensible thing it can do is disallow the syntax entirely.

If JS supported tuples natively, then yes, I'd expect that to be legal syntax.

[fkling]

@not-an-aardvark: Considering that other documentation uses "spread syntax", I'd rather go with that and update this PR accordingly. But I'm curious to see if other maintainers agree on updating the docs in general.
Thanks for the quick review!

[kaicataldo]

"spread syntax" sounds good to me 👍

[fkling]

Updated to "spread syntax".

[platinumazure]

LGTM, thanks for contributing!

[aladdin-add]

merged, thanks for contributing!