From 86aa45e5610f38d2bf58884b478cbd6b4bbed668 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Sat, 9 May 2020 15:51:21 +0200 Subject: [PATCH 01/10] Define definition conventions ... Helps with #730. --- index.bs | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/index.bs b/index.bs index 1ade2a10..8aaa633e 100644 --- a/index.bs +++ b/index.bs @@ -4003,14 +4003,13 @@ determine what Web IDL language feature to use:
The supports(property, value) - method, when called, must run these steps: + method steps are: 1. … ---- - The supports(conditionText) method, when called, - must run these steps: + The supports(conditionText) method steps are: 1. … @@ -4021,8 +4020,7 @@ determine what Web IDL language feature to use:
- The supports(|propertyOrConditionText|, |value|) method, when - called, must run these steps: + The supports(|propertyOrConditionText|, |value|) method steps are: 1. If |value| is given, then: 1. Let property be |propertyOrConditionText|. @@ -14465,8 +14463,9 @@ requirements beyond the normal ones for [=interface types=]. Each {{DOMException}} object has an associated name and message, both [=strings=]. -The DOMException(|message|, |name|) -constructor, when invoked, must run these steps: +The +new DOMException(|message|, |name|) +constructor steps are: 1. Set this's [=DOMException/name=] to |name|. 1. Set this's [=DOMException/message=] to |message|. From 56e58058dfdf9b810617f4b5cc2659ce1bcce633 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Mon, 11 May 2020 18:16:30 +0200 Subject: [PATCH 02/10] initial feedback --- index.bs | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/index.bs b/index.bs index 8aaa633e..58596702 100644 --- a/index.bs +++ b/index.bs @@ -2589,10 +2589,9 @@ in which case the [=default toJSON operation=] is exposed instead.
- To invoke the toJSON() operation of the Transaction - interface, run the following steps: + The toJSON() method steps are: - 1. Let |json| be a new TransactionJSON dictionary. + 1. Let |json| be a new [=map=]. 1. [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »: 1. Let |value| be result of [=get the underlying value|getting the underlying value=] of the [=attribute=] identified by |attr|, @@ -2965,22 +2964,17 @@ a [=static attribute=]. }; - Thus, prose is required to explain the stringification behavior, such - as the following paragraph: + Thus, prose is required to explain the stringification behavior. + We assume that the familyName and + givenName attributes are backed by + family name and given name concepts, respectively.
- Objects that implement the Student - interface must stringify as follows. If the value of the - familyName attribute is - null, the stringification of the - object is the value of the givenName - attribute. Otherwise, if the value of the - familyName attribute is not null, - the stringification of the object is the concatenation of the - value of the givenName attribute, - a single space character, and the value of - the familyName attribute. + The stringification behavior steps are: + + 1. If [=this=]'s family name is null, then return [=this=]'s given name. + 2. Return the concatenation of [=this=]'s given name, followed by U+0020 SPACE, followed by [=this=]'s family name.
From e89870a658e9be80bc16dac82452892f37511511 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Mon, 11 May 2020 18:54:35 +0200 Subject: [PATCH 03/10] attempt to resolve the remainder of #730 --- index.bs | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/index.bs b/index.bs index 58596702..1d503160 100644 --- a/index.bs +++ b/index.bs @@ -1872,11 +1872,19 @@ it declares a [=static attribute=]. Note that in addition to being [=interface m
To get the underlying value of an attribute |attr| given a value |target|, - return the result of performing the actions listed in the description of |attr| that occur on getting, + return the result of performing the actions listed in the getter description of |attr|, or those listed in the description of the inherited attribute, if |attr| is declared to inherit its getter, with |target| as [=this=] if it is not null.
+The getter description of an attribute _attr_, should be of the form “The +attr getter steps are:” followed by a list or “The +attr getter steps are to” followed by an inline description. + +The setter description of an attribute _attr_, should be of the form “The +attr setter steps are:” followed by a list or “The +attr setter steps are to” followed by an inline description. + The [=identifier=] of an [=attribute=] must not be the same as the identifier @@ -2422,6 +2430,10 @@ The following extended attributes are applicable to operations: [{{SecureContext}}], [{{LegacyUnforgeable}}]. +The method description of an operation _operation_, should be of the form “The method +operation steps are:” followed by a list or “The +operation steps are to” followed by an inline description. + 
     DefaultValue :
         ConstValue
@@ -2633,8 +2645,16 @@ Multiple [=constructor operations=] may appear on a given [=interface=].
 For each [=constructor operation=] on the [=interface=], there will be a way to attempt to
 construct an instance by passing the specified arguments.
 
-The prose definition of a [=constructor operation=] must either initialize the value passed as
-[=this=], or throw an exception.
+The constructor description of a [=constructor operation=] must either initialize the value passed
+as [=this=], or throw an exception.
+
+The constructor description of a constructor _constructor_, should be of the form “The
+new constructor constructor steps are:” followed by a list or “The
+new constructor constructor steps are to” followed by an inline description.
+
+
If the constructor does not initialize
+[=this=], one can write “The new Example(init) constructor steps are
+to do nothing.”
 
 See [[#interface-object]] for details on how a [=constructor operation=] is to be implemented.
 
@@ -2770,7 +2790,7 @@ will not be such functionality.
 Defining a special operation  with an [=identifier=]
 is equivalent to separating the special operation out into its own
 declaration without an identifier.  This approach is allowed to
-simplify prose descriptions of an interface’s operations.
+simplify method descriptions of an interface’s operations.
 
 

 
@@ -3986,13 +4006,13 @@ determine what Web IDL language feature to use:
     Even though the IDL is shorter in the second version, two distinctively different concepts are
     conflated in the first argument. Without [=overloaded|overloads=], the question "is property or conditionText paired with value?"
-    is much more difficult to answer without reading the prose definition of the operation. This
+    is much more difficult to answer without reading the method description of the operation. This
     makes the second version remarkably less readable than the first.
 
-    Another consideration is that the prose for [=overloaded=] operations can be specified in
-    separate blocks, which can aid in both reading and writing specifications. This is not the case
-    for [=optional arguments=]. This means that in the first case the specification author can write
-    the prose definition of the operations as:
+    Another consideration is that the method description for [=overloaded=] operations can be
+    specified in separate blocks, which can aid in both reading and writing specifications. This is
+    not the case for [=optional arguments=]. This means that in the first case the specification
+    author can write the method descriptions of the operations as:
 
     

 

From cef8b7b340d9044854d39a9eb6ccf5729b6d4661 Mon Sep 17 00:00:00 2001
From: Anne van Kesteren 
Date: Mon, 11 May 2020 19:41:19 +0200
Subject: [PATCH 04/10] CI nit

---
 index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.bs b/index.bs
index 1d503160..8c4f42bc 100644
--- a/index.bs
+++ b/index.bs
@@ -2653,8 +2653,8 @@ The constructor description of a constructor _constructor_, should be of the for
 new constructor constructor steps are to” followed by an inline description.
 
 
If the constructor does not initialize
-[=this=], one can write “The new Example(init) constructor steps are
-to do nothing.”
+[=this=], one can write “The new Example(init) constructor
+steps are to do nothing.”
 
 See [[#interface-object]] for details on how a [=constructor operation=] is to be implemented.
 

From e5920ef6e2753a5a2b4434b845eb4a0c86ed3cf1 Mon Sep 17 00:00:00 2001
From: Anne van Kesteren 
Date: Tue, 12 May 2020 12:28:03 +0200
Subject: [PATCH 05/10] somewhat more ambitious

---
 index.bs | 57 +++++++++++++++++++++++++-------------------------------
 1 file changed, 25 insertions(+), 32 deletions(-)

diff --git a/index.bs b/index.bs
index 8c4f42bc..4f808f9a 100644
--- a/index.bs
+++ b/index.bs
@@ -1869,19 +1869,11 @@ If an attribute has no static keyword, then it declares a
 it declares a [=static attribute=]. Note that in addition to being [=interface members=],
 [=read only=] [=regular attributes=] can be [=namespace members=] as well.
 
-
-

-    To get the underlying value of an attribute |attr| given a value |target|,
-    return the result of performing the actions listed in the getter description of |attr|,
-    or those listed in the description of the inherited attribute,
-    if |attr| is declared to inherit its getter, with |target| as [=this=] if it is not null.
-

-
-The getter description of an attribute _attr_, should be of the form “The
+The getter steps of an attribute _attr_ should be introduced using text of the form “The
 attr getter steps are:” followed by a list or “The
 attr getter steps are to” followed by an inline description.
 
-The setter description of an attribute _attr_, should be of the form “The
+The setter steps of an attribute _attr_ should be introduced using text of the form “The
 attr setter steps are:” followed by a list or “The
 attr setter steps are to” followed by an inline description.
 
@@ -2430,9 +2422,9 @@ The following extended attributes are applicable to operations:
 [{{SecureContext}}],
 [{{LegacyUnforgeable}}].
 
-The method description of an operation _operation_, should be of the form “The method
-operation steps are:” followed by a list or “The
-operation steps are to” followed by an inline description.
+The method steps of an operation _operation_ should be introduced using text of the form
+“The method operation() steps are:” followed by a list or “The
+operation() steps are to” followed by an inline description.
 
 
     DefaultValue :
@@ -2605,9 +2597,9 @@ in which case the [=default toJSON operation=] is exposed instead.
 
         1.  Let |json| be a new [=map=].
         1.  [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »:
-            1.  Let |value| be result of [=get the underlying value|getting the underlying value=]
-                of the [=attribute=] identified by |attr|,
-                given this.
+            1.  Let |value| be the result of running the [=getter steps=]
+                of the [=attribute=] identified by |attr|
+                on this.
             1.  Set |json|[|attr|] to |value|.
         1.  Return |json|.
     

@@ -2648,9 +2640,10 @@ construct an instance by passing the specified arguments.
 The constructor description of a [=constructor operation=] must either initialize the value passed
 as [=this=], or throw an exception.
 
-The constructor description of a constructor _constructor_, should be of the form “The
-new constructor constructor steps are:” followed by a list or “The
-new constructor constructor steps are to” followed by an inline description.
+The constructor steps of a constructor _constructor_ should be introduced using text of
+the form “The new constructor() constructor steps are:” followed by a list
+or “The new constructor() constructor steps are to” followed by an inline
+description.
 
 
If the constructor does not initialize
 [=this=], one can write “The new Example(init) constructor
@@ -11188,7 +11181,7 @@ default interfaces do not have such steps.
         1.  Let |object| be the result of [=internally create a new object implementing the
             interface|internally creating a new object implementing=] |I|, with |realm| and
             {{NewTarget}}.
-        1.  Perform the actions listed in the description of |constructor|
+        1.  Perform the [=constructor steps=] of |constructor|
             with |values| as the argument values
             and |object| as [=this=].
         1.  Let |O| be |object|, [=converted to an ECMAScript value=].
@@ -11256,7 +11249,7 @@ implement the interface on which the
         1.  Let |object| be the result of [=internally create a new object implementing the
             interface|internally creating a new object implementing=] |I|, with |realm| and
             {{NewTarget}}.
-        1.  Perform the actions listed in the description of |constructor|
+        1.  Perform the [=constructor steps=] of |constructor|
             with |values| as the argument values
             and |object| as [=this=].
         1.  Let |O| be |object|, [=converted to an ECMAScript value=].
@@ -11604,8 +11597,8 @@ in which case they are exposed on every object that [=implements=] the interface
                     [=backing observable array exotic object=] for |attribute|.
                 1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                     to |esValue|.
-            1.  Let |R| be the result of [=get the underlying value|getting the underlying value=]
-                of |attribute| given |idlObject|.
+            1.  Let |R| be the result of running the [=getter steps=]
+                of |attribute| on |idlObject|.
             1.  Return the result of [=converted to an ECMAScript value|converting=] |R| to an
                 ECMAScript value of the type |attribute| is declared as.
 
@@ -11697,7 +11690,7 @@ in which case they are exposed on every object that [=implements=] the interface
                 
             
 
-        1.  Perform the actions listed in the description of |attribute| that occur on setting,
+        1.  Perform the [=setter steps=] of |attribute|,
             with |idlValue| as [=the given value=] and
             |idlObject| as [=this=] if it is not null.
         1.  Return undefined
@@ -11805,13 +11798,13 @@ in which case they are exposed on every object that [=implements=] the interface
             1.  Let |R| be null.
             1.  If |operation| is declared with a [{{Default}}] [=extended attribute=],
                 then:
-                1.  Set |R| be the result of performing the actions listed in
+                1.  Set |R| be the result of running the [=method steps=] of
                     |operation|'s [=corresponding default operation=],
                     with |values| as the argument values
                     and |idlObject| as [=this=] if it is not null.
             1.  Otherwise:
-                1.  Set |R| be the result of performing the actions listed in the
-                    description of |operation|,
+                1.  Set |R| be the result of running the
+                    [=method steps=] of |operation|,
                     with |values| as the argument values
                     and |idlObject| as [=this=] if it is not null.
             1.  Return |R|, [=converted to an ECMAScript value=].
@@ -11889,8 +11882,8 @@ The [=return type=] of the [=default toJSON operation=] must be {{object}}.
         [=list|for each=] [=exposed=] [=regular attribute=] |attr|
         that is an [=interface member=] of |I|, in order:
         1.  Let |id| be the [=identifier=] of |attr|.
-        1.  Let |value| be the result of [=get the underlying value|getting the underlying value=]
-            of |attr| given this.
+        1.  Let |value| be the result of running the [=getter steps=] of
+            of |attr| on this.
         1.  If |value| is a [=JSON type=], then [=map/set=] |map|[|id|] to |value|.
 
 

@@ -12022,12 +12015,12 @@ then there must exist a property with the following characteristics:
         1.  Depending on where stringifier was specified:
             

                  :  on an [=attribute=]
-                 :: Set |V| to the result of performing the actions listed in the description of the attribute that occur when getting
-                    (or those listed in the description of the inherited attribute, if this attribute is declared to
+                 :: Set |V| to the result of running the [=getter steps=] of the attribute
+                    (or those listed in the [=getter steps=] of the inherited attribute, if this attribute is declared to
                     [=inherit its getter=]),
                     with |O| as the object.
                  :  on an [=operation=] with an identifier
-                 :: Set |V| to the result of performing the actions listed in the description
+                 :: Set |V| to the result of running the [=method steps=]
                     of the operation, using |O| as the this value
                     and passing no arguments.
                  :  on an [=operation=] with no identifier

From 78ffc6ec442b8bb1f107ac24d59c6f37b7d56aea Mon Sep 17 00:00:00 2001
From: Domenic Denicola 
Date: Tue, 12 May 2020 17:00:29 -0400
Subject: [PATCH 06/10] More cleanup

---
 index.bs | 163 +++++++++++++++++++++++++++----------------------------
 1 file changed, 81 insertions(+), 82 deletions(-)

diff --git a/index.bs b/index.bs
index 4f808f9a..162c608c 100644
--- a/index.bs
+++ b/index.bs
@@ -1516,12 +1516,12 @@ that are exposed as a convenience to users of objects in the system.
-The algorithm steps for every [=regular operation=], [=regular attribute=] getter, and -[=regular attribute=] setter's defined on an [=interface=] or [=interface mixin=] have access to a +The [=constructor steps=], [=getter steps=], [=setter steps=], and [=method steps=] for the various +[=members=] defined on an [=interface=] or [=interface mixin=] have access to a this value, which is an IDL value of the [=interface=] type that the member is declared on or that [=includes=] the [=interface mixin=] the member is declared on. -[=Attribute=] setter's algorithm steps also have access to the given value, +[=Setter steps=] also have access to the given value, which is an IDL value of the type the [=attribute=] is declared as. [=Interfaces=], [=interface mixins=], [=callback interfaces=] and [=namespaces=] each support a @@ -1869,13 +1869,13 @@ If an attribute has no static keyword, then it declares a it declares a [=static attribute=]. Note that in addition to being [=interface members=], [=read only=] [=regular attributes=] can be [=namespace members=] as well. -The getter steps of an attribute _attr_ should be introduced using text of the form “The -attr getter steps are:” followed by a list or “The -attr getter steps are to” followed by an inline description. +The getter steps of an attribute |attr| should be introduced using text of the form “The +|attr| getter steps are:” followed by a list, or “The |attr| getter steps +are to” followed by an inline description. -The setter steps of an attribute _attr_ should be introduced using text of the form “The -attr setter steps are:” followed by a list or “The -attr setter steps are to” followed by an inline description. +The setter steps of an attribute |attr| should be introduced using text of the form “The +|attr| setter steps are:” followed by a list, or “The |attr| setter steps +are to” followed by an inline description. The [=identifier=] of an [=attribute=] @@ -2422,9 +2422,10 @@ The following extended attributes are applicable to operations: [{{SecureContext}}], [{{LegacyUnforgeable}}]. -The method steps of an operation _operation_ should be introduced using text of the form -“The method operation() steps are:” followed by a list or “The -operation() steps are to” followed by an inline description. +The method steps of an operation |operation| should be introduced using text of the form +“The |operation|(arg1, arg2, ...) method +steps are:” followed by a list, or “The |operation|(arg1, +arg2, ...) method steps are to” followed by an inline description. 
     DefaultValue :
@@ -2597,9 +2598,8 @@ in which case the [=default toJSON operation=] is exposed instead.
 
         1.  Let |json| be a new [=map=].
         1.  [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »:
-            1.  Let |value| be the result of running the [=getter steps=]
-                of the [=attribute=] identified by |attr|
-                on this.
+            1.  Let |value| be the result of running the [=getter steps=] of the [=attribute=]
+                identified by |attr| on [=this=].
             1.  Set |json|[|attr|] to |value|.
         1.  Return |json|.
@@ -2638,7 +2638,7 @@ For each [=constructor operation=] on the [=interface=], there will be a way to construct an instance by passing the specified arguments. The constructor description of a [=constructor operation=] must either initialize the value passed -as [=this=], or throw an exception. +as [=this=], or throw an exception. The constructor steps of a constructor _constructor_ should be introduced using text of the form “The new constructor() constructor steps are:” followed by a list @@ -2646,7 +2646,7 @@ or “The new constructor() constructor steps are to” description.

If the constructor does not initialize -[=this=], one can write “The new Example(init) constructor +[=this=], one can write “The new Example(init) constructor steps are to do nothing.” See [[#interface-object]] for details on how a [=constructor operation=] is to be implemented. @@ -8553,7 +8553,7 @@ JavaScript code. The delay(|ms|) method steps are: - 1. Let |realm| be this's [=relevant Realm=]. + 1. Let |realm| be [=this=]'s [=relevant Realm=]. 1. If |ms| is NaN, let |ms| be +0; otherwise let |ms| be the maximum of |ms| and +0. 1. Let |p| be [=a new promise=] in |realm|. 1. Run the following steps [=in parallel=]: @@ -8580,7 +8580,7 @@ JavaScript code. The validatedDelay(|ms|) method steps are: - 1. Let |realm| be this's [=relevant Realm=]. + 1. Let |realm| be [=this=]'s [=relevant Realm=]. 1. If |ms| is NaN, return [=a promise rejected with=] a {{TypeError}} in |realm|. 1. If |ms| < 0, return [=a promise rejected with=] a {{RangeError}} in |realm|. 1. Let |p| be [=a new promise=] in |realm|. @@ -8606,7 +8606,7 @@ JavaScript code. The addDelay(|ms|, |promise|) method steps are: - 1. Let |realm| be this's [=relevant Realm=]. + 1. Let |realm| be [=this=]'s [=relevant Realm=]. 1. Let |taskSource| be some appropriate [=task source=]. 1. If |ms| is NaN, let |ms| be +0; otherwise let |ms| be the maximum of |ms| and +0. 1. Let |p| be [=a new promise=] in |realm|. @@ -8644,7 +8644,7 @@ JavaScript code. The ready attribute getter steps are: - 1. Return this's [=Environment/ready promise=]. + 1. Return [=this=]'s [=Environment/ready promise=].

@@ -9111,16 +9111,14 @@ for the specific requirements that the use of

[Default]

-If the [{{Default}}] [=extended attribute=] appears on a [=regular operation=], -then it indicates that steps described in the [=corresponding default operation=] -must be carried out when the operation is invoked. +If the [{{Default}}] [=extended attribute=] appears on a [=regular operation=], then it indicates +that the appropriate [=default method steps=] must be carried out when the operation is invoked. The [{{Default}}] extended attribute must [=takes no arguments|take no arguments=]. -The [{{Default}}] extended attribute must not -be used on anything other than a [=regular operation=] -for which a [=corresponding default operation=] has been defined. +The [{{Default}}] extended attribute must not be used on anything other than a [=regular operation=] +that [=has default method steps=] defined.
@@ -11183,7 +11181,7 @@ default interfaces do not have such steps. {{NewTarget}}. 1. Perform the [=constructor steps=] of |constructor| with |values| as the argument values - and |object| as [=this=]. + and |object| as [=this=]. 1. Let |O| be |object|, [=converted to an ECMAScript value=]. 1. Assert: |O| is an object that [=implements=] |I|. 1. Assert: |O|.\[[Realm]] is |realm|. @@ -11250,8 +11248,7 @@ implement the interface on which the interface|internally creating a new object implementing=] |I|, with |realm| and {{NewTarget}}. 1. Perform the [=constructor steps=] of |constructor| - with |values| as the argument values - and |object| as [=this=]. + with |object| as [=this=] and |values| as the argument values. 1. Let |O| be |object|, [=converted to an ECMAScript value=]. 1. Assert: |O| is an object that [=implements=] |I|. 1. Assert: |O|.\[[Realm]] is |realm|. @@ -11691,8 +11688,7 @@ in which case they are exposed on every object that [=implements=] the interface 1. Perform the [=setter steps=] of |attribute|, - with |idlValue| as [=the given value=] and - |idlObject| as [=this=] if it is not null. + with |idlObject| as [=this=] and |idlValue| as [=the given value=]. 1. Return undefined 1. Let |F| be [=!=] CreateBuiltinFunction(|steps|, « », |realm|). 1. Let |name| be the string "set " prepended to |id|. @@ -11702,7 +11698,7 @@ in which case they are exposed on every object that [=implements=] the interface
Note: Although there is only a single property for an IDL attribute, since -accessor property getters and setters are passed a [=this=] +accessor property getters and setters are passed a [=this=] value for the object on which property corresponding to the IDL attribute is accessed, they are able to expose instance-specific data. @@ -11796,17 +11792,12 @@ in which case they are exposed on every object that [=implements=] the interface 1. Let <|operation|, |values|> be the result of passing |S| and |args| to the [=overload resolution algorithm=]. 1. Let |R| be null. - 1. If |operation| is declared with a [{{Default}}] [=extended attribute=], - then: - 1. Set |R| be the result of running the [=method steps=] of - |operation|'s [=corresponding default operation=], - with |values| as the argument values - and |idlObject| as [=this=] if it is not null. - 1. Otherwise: - 1. Set |R| be the result of running the - [=method steps=] of |operation|, - with |values| as the argument values - and |idlObject| as [=this=] if it is not null. + 1. If |operation| is declared with a [{{Default}}] [=extended attribute=], then: + 1. Assert: |operation| [=has default method steps=]. + 1. Set |R| to the result of running the [=default method steps=] for |operation|, + with |idlObject| as [=this=] and |values| as the argument values. + 1. Otherwise, set |R| to the result of running the [=method steps=] of |operation|, + with |idlObject| as [=this=] and |values| as the argument values. 1. Return |R|, [=converted to an ECMAScript value=]. Issue(heycam/webidl#674): |R| is assumed to be an IDL value of the type |op| is declared to return. @@ -11830,60 +11821,69 @@ in which case they are exposed on every object that [=implements=] the interface
Default operations
-Only [=regular operations=] which have a corresponding default operation defined below -may be declared with a [{{Default}}] [=extended attribute=]. +A [=regular operation=] +has default method steps +if its [=identifier=] appears in the first column of the following table. In that case, its +default method steps are those given by the algorithm linked from the second column of +the table, and the operation must have the return type given in the third column of the table. + + + + + + +
[=Identifier=] + [=Default method steps=] + [=Return type=]
"toJSON" + The [=default toJSON steps=] + {{object}}
-
Default toJSON operation
+A [=regular operation=] that does not [=have default method steps=] must not be declared with a +[{{Default}}] [=extended attribute=]. -The [=corresponding default operation=] of the toJSON operation is the [=default toJSON operation=]. -The [=return type=] of the [=default toJSON operation=] must be {{object}}. +
Default toJSON operation
- To invoke the default toJSON operation of [=interface=] |I|, - run the the following steps: + The default toJSON steps for an [=interface=] |I| are: 1. Let |map| be a new [=ordered map=]. 1. Let |stack| be the result of [=create an inheritance stack|creating an inheritance stack=] for [=interface=] |I|. - 1. Invoke [=collect attribute values of an inheritance stack=] on this, - passing it |stack| and |map| as arguments. + 1. Invoke [=collect attribute values of an inheritance stack=] given [=this=], |stack|, and + |map|. 1. Let |result| be [=!=] [$OrdinaryObjectCreate$]({{%ObjectPrototype%}}). 1. [=map/For each=] |key| → |value| of |map|, 1. Let |k| be |key| [=converted to an ECMAScript value=]. 1. Let |v| be |value| [=converted to an ECMAScript value=]. - 1. Perform [=!=] CreateDataProperty(|result|, |k|, |v|). + 1. Perform [=!=] [$CreateDataProperty$](|result|, |k|, |v|). 1. Return |result|.
- To invoke the collect attribute values of an inheritance stack abstract operation - with [=stack=] |stack| and [=ordered map=] |map| as arguments, - run the the following steps: + To collect attribute values of an inheritance stack given a [=platform object=] + |object|, a [=stack=] |stack|, and an [=ordered map=] |map|: 1. Let |I| be the result of [=stack/pop|popping=] from |stack|. - 1. Invoke [=collect attribute values=] on this, - passing it |I| and |map| as arguments. - 1. If |stack| [=stack/is not empty=], - then invoke [=collect attribute values of an inheritance stack=] on this, - passing it |stack| and |map| as arguments. + 1. Invoke [=collect attribute values=] given |object|, |I|, and |map|. + 1. If |stack| [=stack/is not empty=], then invoke + [=collect attribute values of an inheritance stack=] given |object|, |stack|, and |map|.
- To invoke the collect attribute values abstract operation - with [=interface=] |I| and [=ordered map=] |map| as arguments, - run the the following steps: + To collect attribute values given a [=platform object=] |object|, an [=interface=] + |I|, and an [=ordered map=] |map|: - 1. If a toJSON operation with a [{{Default}}] [=extended attribute=] is declared on |I|, then - [=list|for each=] [=exposed=] [=regular attribute=] |attr| - that is an [=interface member=] of |I|, in order: + 1. If a toJSON operation with a [{{Default}}] [=extended attribute=] is declared + on |I|, then [=list/for each=] [=exposed=] [=regular attribute=] |attr| that is an + [=interface member=] of |I|, in order: 1. Let |id| be the [=identifier=] of |attr|. - 1. Let |value| be the result of running the [=getter steps=] of - of |attr| on this. + 1. Let |value| be the result of running the [=getter steps=] of |attr| with |object| as + [=this=]. 1. If |value| is a [=JSON type=], then [=map/set=] |map|[|id|] to |value|.
@@ -12018,11 +12018,10 @@ then there must exist a property with the following characteristics: :: Set |V| to the result of running the [=getter steps=] of the attribute (or those listed in the [=getter steps=] of the inherited attribute, if this attribute is declared to [=inherit its getter=]), - with |O| as the object. + with |O| as [=this=]. : on an [=operation=] with an identifier :: Set |V| to the result of running the [=method steps=] - of the operation, using |O| as the this value - and passing no arguments. + of the operation, with |O| as [=this=] and an empty list as the argument values. : on an [=operation=] with no identifier :: Set |V| to the result of performing the [=stringification behavior=] of the interface. @@ -14474,18 +14473,18 @@ The new DOMException(|message|, |name|) constructor steps are: -1. Set this's [=DOMException/name=] to |name|. -1. Set this's [=DOMException/message=] to |message|. +1. Set [=this=]'s [=DOMException/name=] to |name|. +1. Set [=this=]'s [=DOMException/message=] to |message|. -The name attribute's getter must return this -{{DOMException}} object's [=DOMException/name=]. +The name getter steps are to return +[=this=]'s [=DOMException/name=]. -The message attribute's getter must return this -{{DOMException}} object's [=DOMException/message=]. +The message getter steps are to +return [=this=]'s [=DOMException/message=]. -The code attribute's getter must return the -legacy code indicated in the [=error names table=] for this {{DOMException}} object's -[=DOMException/name=], or 0 if no such entry exists in the table. +The code getter steps are to return the legacy +code indicated in the [=error names table=] for [=this=]'s [=DOMException/name=], or 0 if no such +entry exists in the table. {{DOMException}} objects are [=serializable objects=]. From 450bcaee9d0f9baad9d0396015f77a3edfaf3e5c Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Thu, 14 May 2020 14:13:04 +0200 Subject: [PATCH 07/10] tackle more --- index.bs | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/index.bs b/index.bs index 162c608c..02d307ab 100644 --- a/index.bs +++ b/index.bs @@ -2637,15 +2637,14 @@ Multiple [=constructor operations=] may appear on a given [=interface=]. For each [=constructor operation=] on the [=interface=], there will be a way to attempt to construct an instance by passing the specified arguments. -The constructor description of a [=constructor operation=] must either initialize the value passed -as [=this=], or throw an exception. +The constructor steps of a constructor |constructor| should be introduced using text of +the form “The new |constructor|() constructor steps are:” followed by a list or “The +new |constructor|() constructor steps are to” followed by an inline description. -The constructor steps of a constructor _constructor_ should be introduced using text of -the form “The new constructor() constructor steps are:” followed by a list -or “The new constructor() constructor steps are to” followed by an inline -description. +The constructor steps must do nothing, initialize the value passed as [=this=], or throw an +exception. -

If the constructor does not initialize +

If the constructor does not initialize [=this=], one can write “The new Example(init) constructor steps are to do nothing.” @@ -2783,7 +2782,7 @@ will not be such functionality. Defining a special operation with an [=identifier=] is equivalent to separating the special operation out into its own declaration without an identifier. This approach is allowed to -simplify method descriptions of an interface’s operations. +simplify [=method steps=] of an interface’s operations.

@@ -2984,7 +2983,7 @@ a [=static attribute=].
- The stringification behavior steps are: + The [=stringification behavior=] steps are: 1. If [=this=]'s family name is null, then return [=this=]'s given name. 2. Return the concatenation of [=this=]'s given name, followed by U+0020 SPACE, followed by [=this=]'s family name. @@ -3999,13 +3998,13 @@ determine what Web IDL language feature to use: Even though the IDL is shorter in the second version, two distinctively different concepts are conflated in the first argument. Without [=overloaded|overloads=], the question "is property or conditionText paired with value?" - is much more difficult to answer without reading the method description of the operation. This + is much more difficult to answer without reading the [=method steps=] of the operation. This makes the second version remarkably less readable than the first. - Another consideration is that the method description for [=overloaded=] operations can be + Another consideration is that the [=method steps=] for [=overloaded=] operations can be specified in separate blocks, which can aid in both reading and writing specifications. This is not the case for [=optional arguments=]. This means that in the first case the specification - author can write the method descriptions of the operations as: + author can write the [=method steps=]] of the operations as:
@@ -13356,7 +13355,7 @@ Additionally, [=legacy platform objects=] have internal methods as defined in: with |P| as the name. 1. If the steps indicated that the deletion failed, then return false. 1. Otherwise, |operation| was defined with an identifier: - 1. Perform the steps listed in the description of |operation| with |P| as the only argument value. + 1. Perform [=method steps=] of |operation| with |P| as the only argument value. 1. If |operation| was declared with a [=return type=] of {{boolean}} and the steps returned false, then return false. 1. Return true. @@ -13489,7 +13488,7 @@ internal method as follows. 1. Otherwise, |creating| is false. Perform the steps listed in the interface description to [=set the value of an existing indexed property=] with |index| as the index and |value| as the value. - 1. Otherwise, |operation| was defined with an identifier. Perform the steps listed in the description of + 1. Otherwise, |operation| was defined with an identifier. Perform the [=method steps=] of |operation| with |index| and |value| as the two argument values.
@@ -13509,7 +13508,7 @@ internal method as follows. 1. Otherwise, |creating| is false. Perform the steps listed in the interface description to [=set the value of an existing named property=] with |P| as the name and |value| as the value. - 1. Otherwise, |operation| was defined with an identifier. Perform the steps listed in the description of + 1. Otherwise, |operation| was defined with an identifier. Perform the [=method steps=] of |operation| with |P| and |value| as the two argument values.
@@ -13530,7 +13529,7 @@ internal method as follows. [=determine the value of an indexed property=] with |index| as the index. 1. Otherwise, |operation| was defined with an identifier. Set |value| to the result - of performing the steps listed in the description of |operation| with |index| as the only argument value. + of performing the [=method steps=] of |operation| with |index| as the only argument value. 1. Let |desc| be a newly created [=Property Descriptor=] with no fields. 1. Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=] |value| to an ECMAScript value. @@ -13551,7 +13550,7 @@ internal method as follows. [=determine the value of a named property=] with |P| as the name. 1. Otherwise, |operation| was defined with an identifier. Set |value| to the result - of performing the steps listed in the description of |operation| with |P| as the only argument value. + of performing the [=method steps=] of |operation| with |P| as the only argument value. 1. Let |desc| be a newly created [=Property Descriptor=] with no fields. 1. Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=] |value| to an ECMAScript value. From 1c99206a217cae28244175e82f466b96a66c5e82 Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Thu, 14 May 2020 12:29:27 -0400 Subject: [PATCH 08/10] Pass this to method steps always --- index.bs | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/index.bs b/index.bs index 02d307ab..6baec90d 100644 --- a/index.bs +++ b/index.bs @@ -4004,7 +4004,7 @@ determine what Web IDL language feature to use: Another consideration is that the [=method steps=] for [=overloaded=] operations can be specified in separate blocks, which can aid in both reading and writing specifications. This is not the case for [=optional arguments=]. This means that in the first case the specification - author can write the [=method steps=]] of the operations as: + author can write the [=method steps=] of the operations as:
@@ -13279,11 +13279,11 @@ Additionally, [=legacy platform objects=] have internal methods as defined in: 1. If |O| and |Receiver| are the same object, then: 1. If |O| [=implements=] an interface with an [=indexed property setter=] and |P| [=is an array index=], then: - 1. [=Invoke the indexed property setter=] with |P| and |V|. + 1. [=Invoke the indexed property setter=] on |O| with |P| and |V|. 1. Return true. 1. If |O| [=implements=] an interface with a [=named property setter=] and Type(|P|) is String, then: - 1. [=Invoke the named property setter=] with |P| and |V|. + 1. [=Invoke the named property setter=] on |O| with |P| and |V|. 1. Return true. 1. Let |ownDesc| be LegacyPlatformObjectGetOwnProperty(|O|, |P|, true). 1. Perform [=?=] OrdinarySetWithOwnDescriptor(|O|, |P|, |V|, |Receiver|, |ownDesc|). @@ -13305,7 +13305,7 @@ Additionally, [=legacy platform objects=] have internal methods as defined in: false. 1. If |O| does not implement an interface with an [=indexed property setter=], then return false. - 1. [=Invoke the indexed property setter=] with |P| and |Desc|.\[[Value]]. + 1. [=Invoke the indexed property setter=] on |O| with |P| and |Desc|.\[[Value]]. 1. Return true. 1. If |O| [=support named properties|supports named properties=], |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=], @@ -13323,7 +13323,7 @@ Additionally, [=legacy platform objects=] have internal methods as defined in: 1. If the result of calling IsDataDescriptor(|Desc|) is false, then return false. - 1. [=Invoke the named property setter=] with |P| and |Desc|.\[[Value]]. + 1. [=Invoke the named property setter=] on |O| with |P| and |Desc|.\[[Value]]. 1. Return true. 1. If |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=], then set |Desc|.\[[Configurable]] to true. @@ -13355,7 +13355,8 @@ Additionally, [=legacy platform objects=] have internal methods as defined in: with |P| as the name. 1. If the steps indicated that the deletion failed, then return false. 1. Otherwise, |operation| was defined with an identifier: - 1. Perform [=method steps=] of |operation| with |P| as the only argument value. + 1. Perform [=method steps=] of |operation| with |O| as [=this=] and « |P| » as the + argument values. 1. If |operation| was declared with a [=return type=] of {{boolean}} and the steps returned false, then return false. 1. Return true. @@ -13473,7 +13474,7 @@ internal method as follows.
To invoke an indexed property setter - with property name |P| and ECMAScript value |V|, the following steps must be performed: + on a [=platform object=] |O| with property name |P| and ECMAScript value |V|, the following steps must be performed: 1. Let |index| be the result of calling ToUint32(|P|). 1. Let |creating| be true if |index| is not a [=supported property indices|supported property index=], @@ -13489,13 +13490,13 @@ internal method as follows. [=set the value of an existing indexed property=] with |index| as the index and |value| as the value. 1. Otherwise, |operation| was defined with an identifier. Perform the [=method steps=] of - |operation| with |index| and |value| as the two argument values. + |operation| with |O| as [=this=] and « |index|, |value| » as the argument values.
To invoke a named property setter - with property name |P| and ECMAScript value |V|, the following steps must be performed: + on a [=platform object=] |O| with property name |P| and ECMAScript value |V|, the following steps must be performed: 1. Let |creating| be true if |P| is not a [=supported property name=], and false otherwise. 1. Let |operation| be the operation used to declare the named property setter. @@ -13509,7 +13510,7 @@ internal method as follows. [=set the value of an existing named property=] with |P| as the name and |value| as the value. 1. Otherwise, |operation| was defined with an identifier. Perform the [=method steps=] of - |operation| with |P| and |value| as the two argument values. + |operation| with |O| as [=this=] and « |P|, |value| » as the argument values.
@@ -13529,7 +13530,8 @@ internal method as follows. [=determine the value of an indexed property=] with |index| as the index. 1. Otherwise, |operation| was defined with an identifier. Set |value| to the result - of performing the [=method steps=] of |operation| with |index| as the only argument value. + of performing the [=method steps=] of |operation| with |O| as [=this=] and « + |index| » as the argument values. 1. Let |desc| be a newly created [=Property Descriptor=] with no fields. 1. Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=] |value| to an ECMAScript value. @@ -13550,7 +13552,8 @@ internal method as follows. [=determine the value of a named property=] with |P| as the name. 1. Otherwise, |operation| was defined with an identifier. Set |value| to the result - of performing the [=method steps=] of |operation| with |P| as the only argument value. + of performing the [=method steps=] of |operation| with |O| as [=this=] and « |P| » + as the argument values. 1. Let |desc| be a newly created [=Property Descriptor=] with no fields. 1. Set |desc|.\[[Value]] to the result of [=converted to an ECMAScript value|converting=] |value| to an ECMAScript value. From 72b84c53cbdd0b888c887b2792c9964052cd9cff Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Fri, 15 May 2020 09:10:37 +0200 Subject: [PATCH 09/10] update constructor steps per feedback --- index.bs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 6baec90d..e2380f96 100644 --- a/index.bs +++ b/index.bs @@ -2637,9 +2637,12 @@ Multiple [=constructor operations=] may appear on a given [=interface=]. For each [=constructor operation=] on the [=interface=], there will be a way to attempt to construct an instance by passing the specified arguments. -The constructor steps of a constructor |constructor| should be introduced using text of -the form “The new |constructor|() constructor steps are:” followed by a list or “The -new |constructor|() constructor steps are to” followed by an inline description. +The constructor steps of a [=constructor operation=] that is a member of an interface +named |interface| should be introduced using text of the form “The +new |interface|(arg1, arg2, ...) constructor steps +are:” followed by a list or “The +new |interface|(arg1, arg2, ...) constructor steps +are to” followed by an inline description. The constructor steps must do nothing, initialize the value passed as [=this=], or throw an exception. From 65b99ef0f08e37fff70d889fbd4044dd056695dc Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Fri, 15 May 2020 15:16:47 -0400 Subject: [PATCH 10/10] A few more nits --- index.bs | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/index.bs b/index.bs index e2380f96..6fda469d 100644 --- a/index.bs +++ b/index.bs @@ -2598,8 +2598,7 @@ in which case the [=default toJSON operation=] is exposed instead. 1. Let |json| be a new [=map=]. 1. [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »: - 1. Let |value| be the result of running the [=getter steps=] of the [=attribute=] - identified by |attr| on [=this=]. + 1. Let |value| be the result of running the [=getter steps=] of |attr| on [=this=]. 1. Set |json|[|attr|] to |value|. 1. Return |json|.
@@ -2640,7 +2639,7 @@ construct an instance by passing the specified arguments. The constructor steps of a [=constructor operation=] that is a member of an interface named |interface| should be introduced using text of the form “The new |interface|(arg1, arg2, ...) constructor steps -are:” followed by a list or “The +are:” followed by a list, or “The new |interface|(arg1, arg2, ...) constructor steps are to” followed by an inline description. @@ -11182,8 +11181,7 @@ default interfaces do not have such steps. interface|internally creating a new object implementing=] |I|, with |realm| and {{NewTarget}}. 1. Perform the [=constructor steps=] of |constructor| - with |values| as the argument values - and |object| as [=this=]. + with |object| as [=this=] and |values| as the argument values. 1. Let |O| be |object|, [=converted to an ECMAScript value=]. 1. Assert: |O| is an object that [=implements=] |I|. 1. Assert: |O|.\[[Realm]] is |realm|. @@ -11596,8 +11594,8 @@ in which case they are exposed on every object that [=implements=] the interface [=backing observable array exotic object=] for |attribute|. 1. Set |idlObject| to the IDL [=interface type=] value that represents a reference to |esValue|. - 1. Let |R| be the result of running the [=getter steps=] - of |attribute| on |idlObject|. + 1. Let |R| be the result of running the [=getter steps=] of |attribute| with + |idlObject| as [=this=]. 1. Return the result of [=converted to an ECMAScript value|converting=] |R| to an ECMAScript value of the type |attribute| is declared as.