Re: [w3c/browser-payment-api] editorial: attr/method intros are notes (closes #379) (#438)

domenic requested changes on this pull request.

No need to go for the whole domintro style, but there are a few minor things that should be fixed before merging.

> @@ -787,28 +790,42 @@
         <h2>
           <dfn>shippingAddress</dfn> attribute
         </h2>
-        <p>
-          <a>shippingAddress</a> is populated when the user provides a shipping
-          address. It is null by default. When a user provides a shipping
-          address, the <a>shipping address changed algorithm</a> runs.
+        <p class="note">

Hmm. I am less sure about the attributes than about the methods. Since their behavior isn't defined in these sections at all, maybe it is OK to leave the text as non-note, as long as we don't use any normative keywords. The risk with methods is that people might think the notes are what specs their behavior.

>          </p>
+      </section>
+      <section data-dfn-for="PaymentRequest" data-link-for="PaymentRequest">
+        <h2>
+          <dfn>onshippingaddresschange</dfn> attribute
+        </h2>
         <p>

This is inconsistent with the rest (missing class="note"). But as per above I'd be OK with omitting class="note" for all the attributes...

> @@ -787,28 +790,42 @@
         <h2>
           <dfn>shippingAddress</dfn> attribute
         </h2>
-        <p>
-          <a>shippingAddress</a> is populated when the user provides a shipping
-          address. It is null by default. When a user provides a shipping
-          address, the <a>shipping address changed algorithm</a> runs.
+        <p class="note">

A totally different style you might consider:

- Get rid of the separate sections for each attribute.
- Add normative text to the overall PaymentRequest interface section, or maybe to an attributes subsection: "The shippingAddress and shippingOption attributes must return the values they are initialized to. The onshippingaddresschange and onshippingoptionchange attributes are event handle IDL attributes for the shippingaddresschange and shippingoptionchange events, respectively."
- Introduce "domintro" style notes for web developers. Examples: https://html.spec.whatwg.org/#pixel-manipulation https://w3c.github.io/IndexedDB/#request-api. (You'd have separate domintro boxes for each method + the constructor, plus one for the attributes, I think.)

I think this would help especially with the attributes, to separate the normative parts from the web developer info (e.g. "default value is null" is for the web developer; the normative algorithm that sets it to null takes place in the constructor).

> @@ -1070,10 +1087,10 @@
         <dd>
           This <a>PaymentItem</a> contains the total amount of the payment
           request.
-          <p>
-            <code>total</code> MUST be a non-negative value. This means that
-            the <code>total.amount.value</code> field MUST NOT begin with a
-            U+002D HYPHEN-MINUS character.
+          <p class="note">
+            The <a>total</a>.<a data-lt=
+            "PaymentItem.amount">amount</a>.<a data-lt=
+            "PaymentCurrencyAmount.value">value</a> can't be a negative number.

Maybe "Algorithms in this specification that accept a PaymentDetails dictionary will throw if the total.amount.value is a negative number."

>            remaining user interface to be closed).
         </p>
-        <div class="note">
+        <div class="note" title="Dealing with blocked browser UI">

Honestly this feels like a normative requirement, not a note.

-- 
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/438#pullrequestreview-23563170