Re: [heycam/webidl] Use infra notation in Overloading section (#392)

domenic commented on this pull request.

This is a huge improvement, in my view. I can see how the old version would be nice and concise for mathematicians, but for programmers, this is very explicit and parallels the code you would write much more closely. Great work.

> @@ -2858,17 +2858,16 @@ the inputs to the algorithm needed to compute the set.
 An effective overload set is used, among other things, to determine whether there are ambiguities in the
 overloaded operations, constructors and callers specified on an interface.
 
-The elements of an effective overload set are tuples of the form
-<|callable|, |type list|, |optionality list|>.  If the effective overload
+The elements of an effective overload set are [=tuples=] of the form
+(|callable|, |type list|, |optionality list|).  If the effective overload

It might be nice to `<dfn>` each of these components of the tuple, so that later references to them can refer back to them. You could then describe each briefly, e.g. in a bulleted list or similar.

> @@ -2888,8 +2887,8 @@ the same operation or constructor.
     it is referring to an argument of the extended attribute’s
     [=takes a named argument list|named argument list=].
 
-    1.  Initialize |S| to ∅.
-    1.  Let |F| be a set with elements as follows,
+    1.  Let |S| be an [=ordered set=].
+    1.  Let |F| be an [=ordered set=] with elements as follows,

s/elements/items/g

> @@ -2921,35 +2920,43 @@ the same operation or constructor.
         the argument on which the ellipsis appears counts as a single argument.
 
         Note: So <code>void f(long x, long... y);</code> is considered to be declared to take two arguments.
-
-    1.  Let |m| be the maximum of |maxarg| and |N|.
+    1.  Let |max| be [=max=](|maxarg|, |N|).
     1.  For each operation, extended attribute or callback function |X| in |F|:

Link [=set/For each=]?

>      1.  For each operation, extended attribute or callback function |X| in |F|:
-        1.  Let |n| be the number of arguments |X| is declared to take.
-        1.  Let |t|<sub>0..|n|−1</sub> be a list of types, where |t|<sub>|i|</sub>
-            is the type of |X|’s argument at index |i|.
-        1.  Let |o|<sub>0..|n|−1</sub> be a list of [=optionality values=], where |o|<sub>|i|</sub>
-            is “variadic” if |X|’s argument at index |i| is a final, variadic argument,
-            “optional” if the argument is [=optional argument|optional=],
-            and “required” otherwise.
-        1.  Add to |S| the tuple &lt;|X|, |t|<sub>0..|n|−1</sub>, |o|<sub>0..|n|−1</sub>&gt;.
+        1.  Let |arguments| be the [=list=] of arguments |X| is declared to take.
+        1.  Let |n| be the [=list/size=] of |arguments|.
+        1.  Let |types| be a [=list=] of types.
+        1.  Let |optionality_values| be a list of [=optionality values=].

Usually we camelCase our variables? I'm a big fan of switching to longer-than-one-character variable names, BTW.

> -            1.  For every integer |i|, such that |n| ≤ |i| ≤ |m|−1:
-                1.  Let |u|<sub>0..|i|</sub> be a list of types,
-                    where |u|<sub>j</sub> = |t|<sub>j</sub> (for |j| &lt; |n|) and
-                    |u|<sub>j</sub> = |t|<sub>|n|−1</sub> (for |j| ≥ |n|).
-                1.  Let |p|<sub>0..|i|</sub> be a list of [=optionality values=],
-                    where |p|<sub>j</sub> = |o|<sub>j</sub> (for |j| &lt; |n|) and
-                    |p|<sub>j</sub> = “variadic” (for |j| ≥ |n|).
-                1.  Add to |S| the tuple &lt;|X|, |u|<sub>0..|i|</sub>, |p|<sub>0..|i|</sub>&gt;.
-        1.  Initialize |i| to |n|−1.
-        1.  While |i| ≥ 0:
-            1.  If argument |i| of |X| is not
-                [=optional argument|optional=]
-                (i.e., it is not marked as <code>optional</code> and is not
-                a final, variadic argument), then break this loop.
-            1.  Otherwise, add to |S| the tuple &lt;|X|, |t|<sub>0..|i|−1</sub>, |o|<sub>0..|i|−1</sub>&gt;.
+            1.  [=list/For each=] |i| in [=the range=] |n| to |max|−1, inclusive:

I think we usually use spaces on either side of the minus sign? Also, it's worth confirming this is a minus sign − instead of a dash.

Here and elsewhere.

> +            1.  [=list/For each=] |i| in [=the range=] |n| to |max|−1, inclusive:
+                1.  Let |t| be a [=list=] of types.
+                1.  Let |o| be a [=list=] of [=optionality values=].
+                1.  [=list/For each=] |j| in [=the range=] 0 to |i|, inclusive:
+                    1.  If |j| &lt; |n|, then:
+                        1.  [=list/Append=] |types|[|j|] to |t|.
+                        1.  [=list/Append=] |optionality_values|[|j|] to |o|.
+                    1.  Otherwise:
+                        1.  [=list/Append=] |types|[|n|−1] to |t|.
+                        1.  [=list/Append=] "variadic" to |o|.
+                1.  [=set/Append=] the [=tuple=] (|X|, |t|, |o|) to |S|.
+        1.  Let |i| be |n|−1.
+        1.  [=iteration/While=] |i| ≥ 0:
+            1.  If |arguments|[|i|] is not [=optional argument|optional=]
+                (i.e., it is not marked as "optional" and is not
+                a final, variadic argument), then [=iteration/break=] this loop.

Just say "break", no need for "this loop" now that Infra gives it a nice definition.

> @@ -2972,14 +2979,16 @@ the same operation or constructor.
     identifier <code>f</code> and argument count 4 is:
 
     <pre class="set">
-      { &lt;f1, (DOMString), (required)&gt;,
-        &lt;f2, (Node, DOMString), (required, required)&gt;,
-        &lt;f2, (Node, DOMString, double), (required, required, variadic)&gt;,
-        &lt;f2, (Node, DOMString, double, double), (required, required, variadic, variadic)&gt;,
-        &lt;f3, (), ()&gt;,
-        &lt;f4, (Event, DOMString), (required, required)&gt;,
-        &lt;f4, (Event, DOMString, DOMString), (required, required, optional)&gt;,
-        &lt;f4, (Event, DOMString, DOMString, double), (required, required, optional, variadic)&gt; }
+      « 
+        (f1, « DOMString »,                           « required »),

I wonder if we should change the optionality values to have quotes around them, since technically that's what we do above. Or maybe it's just noise.

> @@ -2858,17 +2858,16 @@ the inputs to the algorithm needed to compute the set.
 An effective overload set is used, among other things, to determine whether there are ambiguities in the
 overloaded operations, constructors and callers specified on an interface.
 
-The elements of an effective overload set are tuples of the form
-&lt;|callable|, |type list|, |optionality list|&gt;.  If the effective overload
+The elements of an effective overload set are [=tuples=] of the form
+(|callable|, |type list|, |optionality list|).  If the effective overload

Also, a lot of places seem to refer to "type list length" and similar; we should ideally switch it to size, and link size.

-- 
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/392#pullrequestreview-53053798