Editorial: use consistent wording for abstract operation preambles #1914

bakkot · 2020-03-24T06:47:21Z

This unifies the wording used to introduce abstract operations. The intent is that the new wording should provide all and only the information in the current wording (except in a couple cases where the existing wording is obviously wrong). This is a step towards #545 (structured headers could be used to generate this text) and #1796 (which wants a consistent place to describe the return type of abstract operations).

We're wildly inconsistent about what information we bother to include in these descriptions. This is more obvious after this PR because the wording is now consistent, but since it doesn't actually make the information included any less consistent, I would prefer we not try to address that here.

This PR also removes abstract operation preambles entirely when they contain no information other than the name of the operation and its arguments (though I am open to going the other direction and such adding introductions everywhere they are currently absent). Edit: went the other direction, this PR now add such introductions to abstract operations which were missing them.

After we land this I will try to make a PR to ecmarkup which enforces this style, at least to some extent.

Thanks to @jmdyck for ecmaspeak-py, which has hardcoded all the many, many forms of preamble currently in use and allowed me to extract the information I needed from them.

ljharb

This is a long PR, so before I read the rest, I want to make sure that these kinds of tweaks are something you consider in scope for this PR (ie, adding correct parentheticals on each argument to indicate their type). Whether to add explicit asserts to match these is something I assume would go in a separate PR.

ljharb · 2020-03-24T15:35:39Z

spec.html

@@ -4124,7 +4122,6 @@ <h1>ThrowCompletion</h1>

      <emu-clause id="sec-updateempty" aoid="UpdateEmpty">
        <h1>UpdateEmpty ( _completionRecord_, _value_ )</h1>
-        <p>The abstract operation UpdateEmpty with arguments _completionRecord_ and _value_ performs the following steps:</p>


i think i'd prefer to always include a preamble; but if you wouldn't want to make it correct/consistent in this PR, then i'm also fine landing this first, and then adding correct preambles in a followup.

It's easy to add them in this PR. I actually had them all in originally and then decided to take them all out instead, so it should just be a matter of reverting the second commit.

That said, they're a lot of noise, so I will maybe wait to push that commit so the more substantive preambles can be reviewed first.

ljharb · 2020-03-24T15:36:41Z

spec.html

@@ -4309,7 +4306,7 @@ <h1>IsGenericDescriptor ( _Desc_ )</h1>

      <emu-clause id="sec-frompropertydescriptor" aoid="FromPropertyDescriptor">
        <h1>FromPropertyDescriptor ( _Desc_ )</h1>
-        <p>When the abstract operation FromPropertyDescriptor is called with Property Descriptor _Desc_, the following steps are taken:</p>
+        <p>The abstract operation FromPropertyDescriptor takes argument _Desc_ (a Property Descriptor or *undefined*). It performs the following steps:</p>


I notice that in some places, we have explicit asserts for any preamble-declared types, but eg in this one, we don't. Is that an example of the inconsistency you don't want to handle in this PR?

Is that an example of the inconsistency you don't want to handle in this PR?

Yes. I agree those would also be good to address, I just don't want to consider them in scope for this.

ljharb · 2020-03-24T15:37:45Z

spec.html

@@ -5322,7 +5317,7 @@ <h1>Testing and Comparison Operations</h1>

    <emu-clause id="sec-requireobjectcoercible" aoid="RequireObjectCoercible">
      <h1>RequireObjectCoercible ( _argument_ )</h1>
-      <p>The abstract operation RequireObjectCoercible throws an error if _argument_ is a value that cannot be converted to an Object using ToObject. It is defined by <emu-xref href="#table-14"></emu-xref>:</p>
+      <p>The abstract operation RequireObjectCoercible takes argument _argument_. It throws an error if _argument_ is a value that cannot be converted to an Object using ToObject. It is defined by <emu-xref href="#table-14"></emu-xref>:</p>


Suggested change

The abstract operation RequireObjectCoercible takes argument _argument_. It throws an error if _argument_ is a value that cannot be converted to an Object using ToObject. It is defined by <emu-xref href="#table-14"></emu-xref>:

The abstract operation RequireObjectCoercible takes argument _argument_ (an ECMAScript language value). It throws an error if _argument_ is a value that cannot be converted to an Object using ToObject. It is defined by <emu-xref href="#table-14"></emu-xref>:

per some of the below ones where this parenthetical exists

ljharb · 2020-03-24T15:37:51Z

spec.html

@@ -5303,7 +5298,7 @@ <h1>CanonicalNumericIndexString ( _argument_ )</h1>

    <emu-clause id="sec-toindex" aoid="ToIndex">
      <h1>ToIndex ( _value_ )</h1>
-      <p>The abstract operation ToIndex returns _value_ argument converted to a non-negative integer if it is a valid integer index value. This abstract operation functions as follows:</p>
+      <p>The abstract operation ToIndex takes argument _value_. It returns _value_ argument converted to a non-negative integer if it is a valid integer index value. It performs the following steps:</p>


Suggested change

The abstract operation ToIndex takes argument _value_. It returns _value_ argument converted to a non-negative integer if it is a valid integer index value. It performs the following steps:

The abstract operation ToIndex takes argument _value_ (an ECMAScript language value). It returns _value_ argument converted to a non-negative integer if it is a valid integer index value. It performs the following steps:

ljharb · 2020-03-24T15:38:27Z

spec.html

@@ -5290,7 +5285,7 @@ <h1>ToLength ( _argument_ )</h1>

    <emu-clause id="sec-canonicalnumericindexstring" aoid="CanonicalNumericIndexString">
      <h1>CanonicalNumericIndexString ( _argument_ )</h1>
-      <p>The abstract operation CanonicalNumericIndexString returns _argument_ converted to a Number value if it is a String representation of a Number that would be produced by ToString, or the string *"-0"*. Otherwise, it returns *undefined*. This abstract operation functions as follows:</p>
+      <p>The abstract operation CanonicalNumericIndexString takes argument _argument_. It returns _argument_ converted to a Number value if it is a String representation of a Number that would be produced by ToString, or the string *"-0"*. Otherwise, it returns *undefined*. It performs the following steps:</p>


Suggested change

The abstract operation CanonicalNumericIndexString takes argument _argument_. It returns _argument_ converted to a Number value if it is a String representation of a Number that would be produced by ToString, or the string *"-0"*. Otherwise, it returns *undefined*. It performs the following steps:

The abstract operation CanonicalNumericIndexString takes argument _argument_ (a String). It returns _argument_ converted to a Number value if it is a String representation of a Number that would be produced by ToString, or the string *"-0"*. Otherwise, it returns *undefined*. It performs the following steps:

ljharb · 2020-03-24T15:38:52Z

spec.html

@@ -5448,7 +5442,7 @@ <h1>IsExtensible ( _O_ )</h1>

    <emu-clause id="sec-isinteger" aoid="IsInteger">
      <h1>IsInteger ( _argument_ )</h1>
-      <p>The abstract operation IsInteger determines if _argument_ is a finite integer Number value.</p>
+      <p>The abstract operation IsInteger takes argument _argument_. It determines if _argument_ is a finite integer Number value. It performs the following steps:</p>


Suggested change

The abstract operation IsInteger takes argument _argument_. It determines if _argument_ is a finite integer Number value. It performs the following steps:

The abstract operation IsInteger takes argument _argument_ (an ECMAScript language value). It determines if _argument_ is a finite integer Number value. It performs the following steps:

bakkot · 2020-03-24T16:41:53Z

@ljharb

I want to make sure that these kinds of tweaks are something you consider in scope for this PR (ie, adding correct parentheticals on each argument to indicate their type)

I would prefer to consider those out of scope for this PR, even though I also would like to have those added at some point. My intent was to have this PR be a very mechanical rewording of the existing prose, rather than introducing any new information.

That said, if you notice any obvious ones as you're reading through and you want to note them as you go rather than someone having to re-discover them all later, feel free to leave comments like the ones above and just mark them as resolved, and I'll collect them into a followup PR once this lands.

michaelficarra · 2020-03-24T21:52:30Z

I would prefer "It performs the following steps when called:" to "It performs the following steps:".

jmdyck · 2020-03-25T00:15:23Z

It seems to me that the "performs the following steps" wording in operation/function preambles is superfluous. (Note that several preambles don't have it, and people don't appear to be confused about them.) If we just dropped it, would any readers not understand when the following steps were performed?

(Or, put it this way: in a real programming language, would you ever write the comment: "When called, this function executes the following statements"?)

spec.html

michaelficarra · 2020-03-25T23:52:18Z

spec.html

@@ -5459,7 +5453,7 @@ <h1>IsInteger ( _argument_ )</h1>

    <emu-clause id="sec-isnonnegativeinteger" aoid="IsNonNegativeInteger">
      <h1>IsNonNegativeInteger ( _argument_ )</h1>
-      <p>The abstract operation IsNonNegativeInteger determines if _argument_ is non-negative integer Number value.</p>
+      <p>The abstract operation IsNonNegativeInteger takes argument _argument_. It determines if _argument_ is non-negative integer Number value. It performs the following steps:</p>


Suggested change

The abstract operation IsNonNegativeInteger takes argument _argument_. It determines if _argument_ is non-negative integer Number value. It performs the following steps:

The abstract operation IsNonNegativeInteger takes argument _argument_. It determines if _argument_ is a non-negative integral Number value. It performs the following steps:

Added the missing "a", but leaving this as "integer" rather than "integral" to match other operations. Feel free to submit a followup PR fixing all of them.

spec.html

bakkot · 2020-03-27T20:37:34Z

i think i'd prefer to always include a preamble

Done.

I would prefer "It performs the following steps when called:" to "It performs the following steps:".

Done.

Needs to resolve conflicts after #1918.

Done.

ljharb

All three commits look good, pending my one question about redundant blank lines.

For posterity (things we've already discussed on our editors call), followups hopefully will:

ensure all AO preamble args have a parenthesized type after them
ensure all of those types are matched with either an explicit list of assertions, or, with a notational convention that implicitly asserts this for all AOs
ensure all AO preambles specify the type(s) of what they return

ljharb · 2020-03-27T22:58:56Z

spec.html

          <p>When an Await rejected function is called with argument _reason_, the following steps are taken:</p>

+


why do we always have/want two blank lines here? can we make it always one?

The ones which got changed here were an artifact of the process I was using. Whitespace is pretty inconsistent in general, so I figured it would be fine, but I can back those changes out if you'd prefer. I'd be happy to make it consistent in a separate PR, though I think would want to wait for the ability to enforce it (cf tc39/ecmarkup#173).

I'm fine waiting on it; i'd just prefer to end up never having two blank lines in a row :-)

Added to my list of desiderata for linting the spec.

bakkot · 2020-03-27T23:22:43Z

ensure all of those types are matched with either an explicit list of assertions, or, with a notational convention that implicitly asserts this for all AOs

There is not yet agreement on exactly this one of these two possible alternatives, just that we would like it to be consistent somehow. There are other possible ways that could happen - for example, it would also be consistent to just leave out the assertions entirely.

jmdyck · 2020-03-28T00:15:42Z

ensure all of those types are matched with either an explicit list of assertions, or, with a notational convention that implicitly asserts this for all AOs

[...] There are other possible ways that could happen - for example, it would also be consistent to just leave out the assertions entirely.

Isn't that the same as @ljharb's second alternative? That is: don't Assert parameter types in the <emu-alg>, just have parenthesized parameter types in the preamble, and then say in 5.2.1 Abstract Operations that the latter have the same effect as Asserts. (If that isn't the suggestion, please clarify.)

bakkot · 2020-03-28T00:20:16Z

If that isn't the suggestion, please clarify.

The suggestion (well, not a suggestion per se, just a statement of possibility) is to omit the modification to 5.2.1, or to modify it in such a way that it does not make mention of Assert in explaining the interpretation of these type parameters.

…1914) The intent is that the new wording should provide all and only the information in the current wording (except in a couple cases where the existing wording is obviously wrong)

... to the 'standard' form introduced in PR tc39#1914.

... to the 'standard' form introduced in PR tc39#1914. (For the non-prescribed part of the standard preamble, I mostly tried to re-use the wording in the existing preamble. This could probably be made more consistent between the different operations, but that wasn't my goal.)

- Move talk of operators out of Number methods, down to where we actually have operators - Move commutative/associative sentences to Notes for Number::multiply and Number::add, just because a Note seems like a better place - Convert Number::subtract's prose into an emu-alg - Convert the preambles of 6 Number methods - to the 'standard' form introduced in PR tc39#1914. - Add standard preambles for numeric methods that don't have one (For the non-prescribed part of the standard preamble, I mostly tried to re-use the wording in the existing preamble. This could probably be made more consistent between the different operations, but that wasn't my goal)

... using the format established in PR tc39#1914.

…tc39#2253) ... using the format established in PR tc39#1914.

bakkot force-pushed the consistent-headers branch from d79a900 to 6bb541f Compare March 24, 2020 06:50

ljharb reviewed Mar 24, 2020

View reviewed changes

ljharb added the editorial change label Mar 24, 2020

michaelficarra reviewed Mar 25, 2020

View reviewed changes

spec.html Outdated Show resolved Hide resolved

michaelficarra reviewed Mar 25, 2020

View reviewed changes

spec.html Show resolved Hide resolved

michaelficarra added editor call to be discussed in the next editor call and removed editor call to be discussed in the next editor call labels Mar 25, 2020

michaelficarra reviewed Mar 25, 2020

View reviewed changes

spec.html Show resolved Hide resolved

michaelficarra reviewed Mar 25, 2020

View reviewed changes

spec.html Show resolved Hide resolved