Re: [heycam/webidl] Clarifications to dictionary semantics (#859)

@TimothyGu commented on this pull request.



> +Dictionaries are always passed by value: the dictionary does not retain a reference to its
+language-specific representation (e.g., the corresponding ECMAScript object). So for example,

I feel like the parts before and after the colon are very different things. To me, having IDL dictionaries be passed by value means (and I'm not saying this is accurate) that in a scenario like:

> 1. Let _dictionary_ be an IDL dictionary.
> 1. Perform some algorithm _X_ given _dictionary_.

where "some algorithm _X_" modifies the given dictionary, then any modifications to _dictionary_ will not be observable directly outside of it.

But I feel like the actual point here is that the ES-to-IDL conversion process destroys all links with the original object, unlike the case with interface types. Maybe we need some different wording to get that across.

> @@ -3877,8 +3877,8 @@ defined with [=optional arguments=] and merged into one,
     };
 </pre>
 
-the [=overload resolution algorithm=] would treat the <var ignore>path</var> argument as [=not
-present=] given the same call <code>stroke(undefined)</code>, and not throw any exceptions.

Oops, this was my bad.

> -<dfn id="dfn-present" export lt="present|not present" for="dictionary member">present</dfn>
-in a dictionary value if the value [=map/exists|contains an entry with the key=]
-given by the member's [=identifier=], otherwise it is [=not present=].
-Dictionary members can also optionally have a <dfn id="dfn-dictionary-member-default-value" for="dictionary member" export>default value</dfn>, which is
-the value to use for the dictionary member when passing a value to a
-[=platform object=] that does
-not have a specified value.  Dictionary members with default values are
-always considered to be present.
+[=Dictionary members=] can be specified as
+<dfn id="required-dictionary-member" export for="dictionary member">required</dfn>, meaning that
+converting a language-specific value to a dictionary requires providing a value for that member.
+They can also be specified as having a
+<dfn id="dfn-dictionary-member-default-value" for="dictionary member" export>default value</dfn>,
+which is the value used by default when author code or specification text does not provide a value
+for that member. Note that [=dictionary member/required=] dictionary members only have meaning for
+dictionaries used as operation arguments; members should be left optional if a dictionary is only

I feel the "only have meaning" part isn't clear: _of course_ the word "required" has meaning in general!

How about

Note that specifying dictionary members as required only has an observable effect when converting other representations of dictionaries (like an ECMAScript value supplied as an argument to an [operation](https://heycam.github.io/webidl/#dfn-operation)) to an IDL dictionary. Specification authors should leave members optional in all other cases, including when a dictionary type is used solely as the [return type](https://heycam.github.io/webidl/#dfn-return-type) of [operations](https://heycam.github.io/webidl/#dfn-operation).

We should also define "optional" as "not required" in the context of dictionary members.

>  
 <p class="note">
-    In the ECMAScript binding, a value of <emu-val>undefined</emu-val> is treated as
-    [=not present=], or will trigger the [=dictionary member/default value=] where applicable.
+    In the ECMAScript binding, a value of <emu-val>undefined</emu-val> for the property
+    corresponding to a [=dictionary member=] is treated the same as omitting that property. Thus, it
+    will cause an error if the member is [=dictionary member/required=], or will trigger the
+    [=dictionary member/default value=] if one is present, or will result in no [=map/entry=]
+    existing in the dictionary value otherwise.
+</p>
+
+<p class="advisement">
+    As with [=optional argument/default value|operation argument default values=], it is strongly
+    encouraged not to use <emu-val>true</emu-val> as the [=dictionary member/default value=] for
+    {{boolean}}-typed [=dictionary members=], as this can be confusing for authors who might
+    otherwise expect the default conversion of <emu-val>undefined</emu-val> to be used (i.e.,
+    <emu-val>false</emu-val>).

Cite https://w3ctag.github.io/design-principles/ (https://w3ctag.github.io/design-principles/#prefer-dict-to-bool in particular)?

>  </p>
 
 An [=ordered map=] with string [=map/keys=] can be implicitly treated as a dictionary value of a
 specific dictionary |D| if all of its [=map/entries=] correspond to [=dictionary members=], in the
-correct order and with the correct types, and with appropriate [=map/entries=] for any required
-dictionary members.
+correct order and with the correct types, and with appropriate [=map/entries=] for any required or

Is the order requirement really important? Also, what order is this? I assume it's the order members appear in the actual IDL source. However, this interpretation runs into trouble later as the ES-to-IDL conversion algorithm seems to use lexicographic order within each inherited dictionary.

Maybe we could just get rid of the order requirement?

> @@ -7756,9 +7758,7 @@ the object (or its prototype chain) correspond to [=dictionary members=].
     running the following algorithm (where |D| is the [=dictionary type=]):
 
     1.  If <a abstract-op>Type</a>(|esDict|) is not Undefined, Null or Object, then [=ECMAScript/throw=] a {{ECMAScript/TypeError}}.
-    1.  Let |idlDict| be an empty dictionary value of type |D|;
-        every [=dictionary member=]
-        is initially considered to be [=not present=].
+    1.  Let |idlDict| be an empty [=ordered map=].

I think having the "representing a dictionary of type _D_" information somewhere would still be beneficial.

-- 
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/859#pullrequestreview-381442649