Re: [w3c/browser-payment-api] Editorial: move+rework examples (#553)

bentian approved this pull request.



> @@ -182,6 +182,254 @@
         </section>
       </section>
     </section>
+    <section class="informative">
+      <h2>
+        Examples of usage
+      </h2>
+      <p>
+        In order to use the API, the developer needs to provide and keep track
+        of an number of key pieces of information. Each of these bits of

s/an/a

Also 'Each of' seems redundant.

> +        In order to use the API, the developer needs to provide and keep track
+        of an number of key pieces of information. Each of these bits of
+        information are passed to the <a>PaymentRequest</a> constructor as
+        arguments, and subsequently used to update the payment request being
+        displayed to the user. Namely, these bits of information are:
+      </p>
+      <ul>
+        <li>The <var>methodData</var>: a sequence of <a>PaymentMethodData</a>s
+        that represents the <a>payment methods</a> that the site supports
+        (e.g., "we support card-based payments, but only Visa and MasterCard
+        credit cards.").
+        </li>
+        <li>The <var>details</var>: The details of the transaction, as a
+        <a>PaymentDetailsInit</a> dictionary. This includes total cost, and
+        optionally a list of goods or services being purchased, for physical
+        goods, any shipping options. Additionally, it can optionally include

s/any/and

> @@ -182,6 +182,254 @@
         </section>
       </section>
     </section>
+    <section class="informative">
+      <h2>
+        Examples of usage
+      </h2>
+      <p>
+        In order to use the API, the developer needs to provide and keep track
+        of an number of key pieces of information. Each of these bits of
+        information are passed to the <a>PaymentRequest</a> constructor as
+        arguments, and subsequently used to update the payment request being
+        displayed to the user. Namely, these bits of information are:
+      </p>
+      <ul>
+        <li>The <var>methodData</var>: a sequence of <a>PaymentMethodData</a>s

nit: Capitalize 'a' to conform with the other two paragraphs.

> +      <ul>
+        <li>The <var>methodData</var>: a sequence of <a>PaymentMethodData</a>s
+        that represents the <a>payment methods</a> that the site supports
+        (e.g., "we support card-based payments, but only Visa and MasterCard
+        credit cards.").
+        </li>
+        <li>The <var>details</var>: The details of the transaction, as a
+        <a>PaymentDetailsInit</a> dictionary. This includes total cost, and
+        optionally a list of goods or services being purchased, for physical
+        goods, any shipping options. Additionally, it can optionally include
+        "modifiers" to how payments are made. For example, "if you pay with a
+        credit card of type X, it incurs a US$3.00 processing fee".
+        </li>
+        <li>The <var>options</var>: Optionally, a list of things that the site
+        needs to deliver the good or service (e.g., for physical goods, the
+        merchant will typically need an physical address to ship to. For

s/an/a

> +              supportedMethods: "https://example.com/bobpay",
+              data: {
+                merchantIdentifier: "XXXX",
+                bobPaySpecificField: true,
+              },
+            },
+          ];
+        </pre>
+      </section>
+      <section>
+        <h3>
+          The <code>details</code> argument
+        </h3>
+        <p>
+          The <var>details</var> contains information about the transaction
+          that the user is being asked to complete such as the line items in an

A `,` after `complete` would be be clearer:
`that the user is being asked to complete, such as the line items in an order.`

> +        <a>PaymentDetailsInit</a> dictionary. This includes total cost, and
+        optionally a list of goods or services being purchased, for physical
+        goods, any shipping options. Additionally, it can optionally include
+        "modifiers" to how payments are made. For example, "if you pay with a
+        credit card of type X, it incurs a US$3.00 processing fee".
+        </li>
+        <li>The <var>options</var>: Optionally, a list of things that the site
+        needs to deliver the good or service (e.g., for physical goods, the
+        merchant will typically need an physical address to ship to. For
+        digital goods, an email will usually suffice).
+        </li>
+      </ul>
+      <p>
+        Once a <a>PaymentRequest</a> is constructed, it's presented to the end
+        user via the <a>show()</a> method. The <a>show()</a> returns a promise
+        that, once the user confirms request for payment, results in a

ReSpec says error for the above 2 `show()` links.

> Found linkless element with text 'show()' but no matching <dfn>

> +              const response = await request.show();
+              await validateResponse(response);
+            } catch (err) {
+              // AbortError, SecurityError
+              console.error(err);
+            }
+          }
+          async function validateResponse(response) {
+            try {
+              if (await checkAllValuesAreGood(response)) {
+                await response.complete("success");
+              } else {
+                await response.complete("fail");
+              }
+            } catch (err) {
+              // Something went wrong... but don't maybe finished ok?

Do you mean 'maybe ok to finish'?

> +        displayed to the user. Namely, these bits of information are:
+      </p>
+      <ul>
+        <li>The <var>methodData</var>: a sequence of <a>PaymentMethodData</a>s
+        that represents the <a>payment methods</a> that the site supports
+        (e.g., "we support card-based payments, but only Visa and MasterCard
+        credit cards.").
+        </li>
+        <li>The <var>details</var>: The details of the transaction, as a
+        <a>PaymentDetailsInit</a> dictionary. This includes total cost, and
+        optionally a list of goods or services being purchased, for physical
+        goods, any shipping options. Additionally, it can optionally include
+        "modifiers" to how payments are made. For example, "if you pay with a
+        credit card of type X, it incurs a US$3.00 processing fee".
+        </li>
+        <li>The <var>options</var>: Optionally, a list of things that the site

Would be good to mention PaymentOptions dictionary like the other two. For example,
`Optionally, a list of things as <a>PaymentOptions</a> that the site ...`

> +                amount: { currency: "USD", value: "55.00" },
+              },
+              {
+                label: "Sales Tax",
+                amount: { currency: "USD", value: "5.00" },
+              },
+            ],
+            total: {
+              label: "Total due",
+              amount: { currency: "USD", value: "65.00" },
+            },
+          };
+        </pre>
+        <section>
+          <h4>
+            shipping options

nit: Capitalize 's'hipping

-- 
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/553#pullrequestreview-51105893