Re: [w3c/browser-payment-api] Editorial changes (#559)

marcoscaceres requested changes on this pull request.



> @@ -2557,7 +2573,8 @@
         <ol class="algorithm">
           <li>If the <var>request</var>.<a>[[\updating]]</a> is true, then
           terminate this algorithm and take no further action. Only one update
-          may take place at a time. This should never occur.
+          may take place at a time. The <a>user agent</a> user interface should

Please revert this, as it introduces a MAY. Also, when implementing, the original is more clear - as it's converted to an `assert()` in each implementation. 

> @@ -2601,7 +2618,8 @@
           attribute of <var>request</var> is null or if the <a data-lt=
           "PaymentRequest.shippingOption">shippingOption</a> attribute of <var>
             request</var> is null, then terminate this algorithm and take no
-            further action. This should never occur.
+            further action. The <a>user agent</a> user interface should ensure

Please also revert this one - as above. 

>        </p>
       <p data-link-for="PaymentRequest">
-        The <a>user agent</a> as a whole has a single <dfn>payment request is
-        showing</dfn> boolean, initially false. This is used to prevent
-        multiple <a>PaymentRequest</a>s from being shown, via their
-        <a>show()</a> method, at the same time.
+        Because the simultaneous display of multiple <a>PaymentRequest</a> user
+        interfaces may confuse the user, this specification limits the <a>user

s/may/might (we try not avoid putting conformance requirements on users in this spec)

>        </p>
       <p data-link-for="PaymentRequest">
-        The <a>user agent</a> as a whole has a single <dfn>payment request is
-        showing</dfn> boolean, initially false. This is used to prevent
-        multiple <a>PaymentRequest</a>s from being shown, via their
-        <a>show()</a> method, at the same time.
+        Because the simultaneous display of multiple <a>PaymentRequest</a> user
+        interfaces may confuse the user, this specification limits the <a>user
+        agent</a> to displaying one at a time via the <a>show()</a> method.
+        This is ensured by a <dfn>payment request is showing</dfn> boolean,
+        global to the browser and initially false.

Please remove the ", global to the browser and initially false." Avoids duplication.  

> @@ -776,6 +778,10 @@
             for the request to another app. In this situation, <a>abort()</a>
             will reject the returned <a>Promise</a>.
           </p>
+          <p>

s/`<p>`/`<p class="note">`

> @@ -1091,6 +1097,11 @@
           will be <a>JSON-serialized</a>.
         </dd>
       </dl>
+      <p class="note">
+        The value of <code>supportedMethods</code> was changed from array to
+        string, but the name was left as a plural to maintain compatibility
+        with deployed software.

s/deployed software/existing content on the Web.

> @@ -1410,6 +1421,11 @@
           will be <a>JSON-serialized</a>.
         </dd>
       </dl>
+      <p class="note">

This should only appear once in the document. I suggest dropping this one. 

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/browser-payment-api/pull/559#pullrequestreview-50233983