Re: [heycam/webidl] Editorial: make more iterator-related stuff imperative (#862)

TimothyGu commented on this pull request.



> -        *   the platform object |object|,
-        *   the identifier "<code>entries</code>", and
-        *   the type "<code>method</code>".
-    1.  Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
-        is declared.
-    1.  If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
-        {{ECMAScript/TypeError}}.
-    1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
-        with |object| as its [=default asynchronous iterator object/target=],
-        "<code>value</code>" as its [=default asynchronous iterator object/kind=], and
-        [=default asynchronous iterator object/is finished=] set to false.
-    1.  Run the [=asynchronous iterator initialization steps=] for |interface| with |object| and
-        |iterator|, if any such steps exist.
-    1.  Return |iterator|.
+<div algorithm>
+    To <dfn oldids="es-iterable-entries,es-iterable-keys,es-iterable-values">define the iterability</dfn>

I tried to get used to the name of this algorithm but I don't think I can. "Iterability" is just too different from the likes of "regular operations", etc. How about "to define the iteration methods"?

> -    1.  Let |interface| be the [=interface=] on which the [=asynchronously iterable declaration=]
-        is declared.
-    1.  If |object| does not [=implement=] |interface|, then [=ECMAScript/throw=] a
-        {{ECMAScript/TypeError}}.
-    1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for |interface|
-        with |object| as its [=default asynchronous iterator object/target=],
-        "<code>value</code>" as its [=default asynchronous iterator object/kind=], and
-        [=default asynchronous iterator object/is finished=] set to false.
-    1.  Run the [=asynchronous iterator initialization steps=] for |interface| with |object| and
-        |iterator|, if any such steps exist.
-    1.  Return |iterator|.
+<div algorithm>
+    To <dfn oldids="es-iterable-entries,es-iterable-keys,es-iterable-values">define the iterability</dfn>
+    of [=interface=] |definition| on |target|, given [=Realm=] |realm|, run the following steps:
+
+    1.  If |definition| has an [=indexed property getter=], then:

I feel like the flow here could be enhanced a bit to make clear the implication and mutual exclusivity relations of the conditions, like:

1. If _definition_ has an indexed property getter, then:
   1. …
   1. If _definition_ has a value iterator, then …
1. Otherwise, if _definition_ has a pair iterator, then …
1. Otherwise, if _definition_ has an asynchronously iterable declaration, then …

You could also consider a switch-like syntax.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/heycam/webidl/pull/862#pullrequestreview-380763253