search

whatwg / webidl

Web IDL Standard
https://webidl.spec.whatwg.org/
Other
405 stars 162 forks source link

Consider a pattern for dictionary arguments which must have at least one member #903

Open domenic opened 4 years ago

domenic commented 4 years ago

This is a continuation of https://github.com/heycam/webidl/issues/130.

There are a number of places on the platform that end up marking their dictionary arguments as "optional", even though they're not really optional. They just have a requirement that can't be expressed in IDL today: at least one member must be present. Examples:

I think we might have reached the point where it's worth making this pattern first-class. It would remove a bit of spec boilerplate in each spec, and it would make the IDL less confusing for readers (see e.g. https://github.com/whatwg/dom/issues/332).

I suggest something like

partial interface MutationObserver {
  void observe(Node target, [OneMemberRequired] MutationObserverInit options);
};

I believe this explicitness sidesteps the problems mentioned in #130, where we were worried that people would not properly mark truly-optional trailing dictionaries as optional. You have to really know what you're doing to use this kind of extended attribute.

We could also use a keyword (onememberrequired MutationObserverInit options) for symmetry with optional. In general the dividing line between syntax and extended attributes is kind of blurry in Web IDL; see some discussion in https://github.com/heycam/webidl/pull/857#issuecomment-604388055.

annevk commented 4 years ago

It doesn't seem like this would simplify the logic for observe(). And I'm also not sure how it would help getUserMedia() as what it really wants are true or dictionary values, not just any values.

domenic commented 3 years ago

Another instance: https://github.com/WICG/app-history/issues/52

saschanaz commented 3 years ago

It doesn't seem like this would simplify the logic for observe().

IMO this one is more about the syntax rather than about simplifying logic. I can imagine an author write an operation with the one-member-required behavior in mind and then get yelled by IDL validator. It also affects TypeScript code generation, BTW.

domenic commented 3 years ago

I'm mostly interested in this for logic-simplification; comments are fine for readers. But I think we have enough cases now where it would simplify the logic.