Editorial: Examine+reduce the diversity of forms in PR #2877

[jmdyck]

At the latest editors call, I was invited to expand on #2877 (comment), giving specific cases instead of just counts. That's what this PR does.

Most of the commit messages have a relevant excerpt from that comment and some discussion.

[michaelficarra]

For ab4c875 and 7550efd, I strongly prefer keeping the "either".

Similarly, for c579c42 I prefer keeping "any of" or "one of", and for a508279 I prefer keeping "one of".

[jmdyck]

Okay, now that I have a better idea of editors' preferences, I've dropped the "descriptions" commits. Instead, since this PR is labelled "establishes editorial conventions", I've attempted to formulate a convention and then supply commits to bring things into line.

---

We often need to express that the value of an alias (or other meta-expression) belongs to some target set of values. E.g.,

• In an algorithm, to check whether the value of _X_ is a String value, we say if _X_ is a String.
• In a structured header, to assert that parameter _X_ is a String value, we say _X_: a String.

In both of the above examples, the target set of values is expressed the same way ("a String"). But things get interesting when the target set cannot be expressed that simply. For example,

• in an algorithm, we might say if _X_ is either a String or *undefined*, whereas
• in a structured header, we would say _X_: a String or *undefined*.

(I.e., one uses "either" and the other doesn't.)

So here, we consider when the target set is a union of smaller sets, expressed as a disjunction of descriptive terms, which I'll generalize as {D}.

For example, a {D} might be:

• a String
• *undefined*
• ~empty~
• an Object that has a [[Foo]] internal slot
• a List of <things>
• a normal completion containing <something>

The wording we use for the disjunction depends on its context, specifically what precedes it.

(1) When it's preceded by prose (typically the word "is")...

The conventional forms are:

• {D}
• either {D} or {D}
• one of {D}, {D}, ..., or {D}

E.g.:

• _X_ is *NaN*
• _Y_ is either a Number or a BigInt
• _Z_ is one of an Object, *null*, or *undefined*

[The 4 new commits bring the spec in line with this convention.]

(2) Otherwise, the disjunction is preceded by:

• a colon (when a structured header declares the 'type' of a parameter or return value)
• the start of a table cell (when a table that 'declares' the fields of a record or the internal slots of an object
  gives the 'type' of the field or slot, typically in the column labelled "Value Type"), or
• a left paren (in an 'inline' declaration of a Record schema).

Here, the conventional forms don't use "either" or "one of":

• {D}
• {D} or {D}
• {D}, {D}, ..., or {D}

E.g.:

• _X_ : a String
• _Y_ : a Number or a BigInt
• _Z_ : an Object, *null*, or *undefined*

But if {D} or {D} would be ambiguous, then use one of these forms:

• either {D} or {D}
• either {D}, or {D}

For example, a List of Strings or *undefined* is ambiguous. It could mean:

• a List of (Strings or *undefined) or
• (a List of Strings) or *undefined*

By using 'either', we can say (respectively):

• a List of either Strings or *undefined* or
• either a List of Strings or *undefined*

(Similarly, a normal completion containing {D} or {D} is ambiguous and so needs 'either'.)

The version with the comma is helpful when the first {D} is itself complicated, e.g.:

• either a normal completion containing either a Number or a BigInt, or a throw completion

[No commits needed.]

[jmdyck]

(Looks like ecmarkup doesn't like either a normal completion containing one of A, B, or C, or a throw completion.)

[michaelficarra]

@jmdyck That summary LGTM.

[syg]

I think the "one of an X" form sounds strange. From the editor call discussion, the following would sound more natural.

A disjunct is either a type with >1 inhabitant (styled as X below) or a constant (styled as "foo" below).

• If there are exactly 2 disjuncts and both disjuncts are types, or both disjuncrs are constants, say "either {D} or {D}"
• If there are exactly 2 disjuncts and one disjunct is a type and the other is a constant, put the type before the constant, and say "either X or "foo""
• If there are >=3 disjuncts and all disjuncts are types with >1 inhabitants, say "either an X, a Y, or a Z"
• If there are >=3 disjuncts and all disjuncts are constants, say "one of "foo", "bar", or "baz""
• If there are >=3 disjuncts and some are types and some are constants, put all the types before the constants, and say "either an X, a Y, a Z, or one of "foo", "bar", or "baz""

[jmdyck]

Okay, I made some more changes and then re-divided things with respect to @syg's bullets.

• If there are exactly 2 disjuncts and both disjuncts are types, or both disjuncts are constants, say "either {D} or {D}"

2 commits, inserting "either" to a few cases that didn't have a prefix (5 cases with two types, 3 cases with two constants).

• If there are exactly 2 disjuncts and one disjunct is a type and the other is a constant, put the type before the constant, and say "either X or "foo""

1 commit, swapping the order in 1 case.

• If there are >=3 disjuncts and all disjuncts are types with >1 inhabitants, say "either an X, a Y, or a Z"

2 commits, inserting "either".

The second commit is where the disjunction is after "is not", in case you want to consider negatives differently.

• If there are >=3 disjuncts and all disjuncts are constants, say "one of "foo", "bar", or "baz""

3 commits,

• changing "either" to "one of" (1 case),
• changing "any of" to "one of" (22 cases), and
• inserting "one of" (1 case).

• If there are >=3 disjuncts and some are types and some are constants, put all the types before the constants, and say "either an X, a Y, a Z, or one of "foo", "bar", or "baz""

Currently, the spec has only 5 occurrences of this, and they're all 'degenerate', in that either the number of types or the number of constants is 1.

• For 3+ types + 1 constant, I assumed either an X, a Y, a Z, or "foo" (1 commit to put the constant last in 1 case).
• For 1 type + 2 constants, I assumed either an X or one of "foo" or "bar" (1 commit to insert "or one of" in 3 cases).

Personally, I think the changes of that last commit aren't an improvement. Note that all 3 cases are embedded within a "normal completion" type, so e.g., the status quo's
either a normal completion containing either an Object, *null*, or *undefined*, or a throw completion
is changed to:
either a normal completion containing either an Object or one of *null* or *undefined*, or a throw completion

[bakkot]

From discussion this all looks good except in the case of mixing types and constants, where we'd prefer to mix them in a single list (still with the constants at the end) and use either rather than one of regardless of how many items there are. (Contrary to the last call, now that we've seen it written out- thanks!)

(Also I'll need to update ecmarkup to understand "one of".)

[jmdyck]

From discussion this all looks good except in the case of mixing types and constants, where we'd prefer to mix them in a single list (still with the constants at the end) and use either rather than one of regardless of how many items there are.

Okay, I've dropped my last commit, so those 3 cases have reverted to the format you describe.

[bakkot]

LGTM, thanks for doing this.

[syg]

lgtm, thanks for bearing with all the requests