Define members in the IDL (not separately)

[pejic]

Currently the spec code defines members in a separate <dl dfn-for="Type"> block. It has been recommended that the spec rely on the references to the IDL.

For example isPayment and rpId are currently defined below the IDL.

    <xmp class="idl">
    [...]
    dictionary AuthenticationExtensionsPaymentInputs {
      boolean isPayment;

      // Only used for authentication.
      USVString rpId;
      [...]
    };
    </xmp>

    <dl dfn-type="dict-member" dfn-for="AuthenticationExtensionsPaymentInputs">
      :  <dfn>isPayment</dfn> member
      :: Indicates that the extension is active.

      :  <dfn>rpId</dfn> member
      :: The [=Relying Party=] id of the credential(s) being used. Only used at authentication time; not registration.

      [...]

    </dl>

Instead, remove the <dl> and <dfn> and reference the member.

    <xmp class="idl">
    [...]
    dictionary AuthenticationExtensionsPaymentInputs {
      boolean isPayment;

      // Only used for authentication.
      USVString rpId;
      [...]
    };
    </xmp>

    :  {{AuthenticationExtensionsPaymentInputs/isPayment}}
    :: Indicates that the extension is active.

    :  {{AuthenticationExtensionsPaymentInputs/rpId}}
    :: The [=Relying Party=] id of the credential(s) being used. Only used at authentication time; not registration.

    [...]

This issue was raised by @domfarolino in #286 (comment)_

[pejic]

Another option (which matches the style in the example in https://dom.spec.whatwg.org/#dictdef-addeventlisteneroptions more closely) would be the following:

    <ul class="brief">
      <li><dfn dfn-type="dict-member" dfn-for="AuthenticationExtensionsPaymentInputs">isPayment</dfn> (Indicates that the extension is active.)

      <li><dfn dfn-type="dict-member" dfn-for="AuthenticationExtensionsPaymentInputs">rpId</dfn> (The [=Relying Party=] id of the credential(s) being used. Only used at authentication time; not registration.)

[domfarolino]

I don't think it matches the style. Note how when you click on the word "passive" in https://dom.spec.whatwg.org/#ref-for-dom-addeventlisteneroptions-passive%E2%91%A1, it takes you to the definition which is inside the IDL. That's what you want. Your comment above is an example of the definition existing outside of the IDL, or a new definition altogether. If you want some explanatory text describing what each field is for, then you should create a domintro box: developer-friendly non-normative text, like in https://dom.spec.whatwg.org/#ref-for-dom-event-event. Don't add more definitions, and keep the actual term defined in IDL.

[pejic]

@domfarolino Thanks for clarifying that. I had been incorrectly looking at the <ul class=brief> block rather than the <ul class=domintro> block.

The class domintro is styled by (at least) these stylesheets:

• <link crossorigin href="https://resources.whatwg.org/standard.css" rel="stylesheet">
• <link crossorigin href="https://resources.whatwg.org/spec.css" rel="stylesheet">

Particularly "For web developers (non-normative)" comes from these stylesheets. However, the secure payment confirmation spec (https://www.w3.org/TR/secure-payment-confirmation/) does not include those stylesheets whereas https://dom.spec.whatwg.org does include those stylesheets. I do not know whether these stylesheets should be included or whether repos in org:w3c do not include these stylesheets intentionally.

[domfarolino]

Hopefully this helps: https://github.com/WICG/nav-speculation/blob/main/prerendering.bs#L144-L179