Should BCD represent dictionaries as their own entries?

[foolip]

This has been discussed in various places, but there doesn't seem to be a dedicated issue.

I raised it in #7039 (comment), where @ddbeck and @Elchi3 pointed to previous discussion in #6265.

My take:

Web IDL dictionaries are a spec author convenience for describing plain JavaScript objects, unlike interfaces which come with "interface objects" which can be used feature testing, for example.

Dictionaries are typically used as arguments, often for init dictionaries for constructors, and sometimes as the return types for methods.

From a quick search of webref there are over 600 dictionaries.

[saschanaz]

#6810 is about removing them. I think they at least should have their own directory rather than being mixed in api/.

[sideshowbarker]

My vote is that we stop representing IDL dictionaries as their own entries in BCD — for the reasons that:

• dictionaries as such in fact don’t even exist as far as web developers are concerned, and treating them separately in BCD and MDN has the effect of worse convenience for web developers, rather than better convenience
• dictionary names aren’t exposed to web content directly for web developers to observe — and therefore, we shouldn’t expose them as such in BCD

Longer rationale, keyed off the following statement from the issue description:

Web IDL dictionaries are a spec author convenience for describing plain JavaScript objects

I think “convenience” is the key word here — and I think the important distinction is that dictionaries are not a convenience for web developers. In fact I think it could reasonably said that having dictionaries documented separately in MDN creates an unnecessary level of indirection that’s an inconvenience for web developers — because web developers only care, for example, what parameters a particular method actually has, and they want to see that information at point of use, rather than needing to navigate over to yet another separate MDN article to find the information they need.

In other words, if we’re intending to optimize for the information needs of web developers, then we need to consider that web developers have zero information need to know anything about dictionaries.

It’s true that along with dictionaries being a convenience for spec authors, we could say they’re a convenience for those of us working on MDN and BCD — in the cases where the dictionaries let us avoid needing to write and maintain identical descriptions in MDN in multiple place, and to avoid needing to track identical browser-support data in multiple places in BCD.

But when we have the choice between optimizing for our own convenience as BCD/MDN maintainers, versus optimizing for the information needs of web developers, it seems pretty clear we should choose to optimize for web-developer needs.

And while I suppose it could be said too that dictionaries are also a browser-engine implementation convenience — since browsers do generally handle them internally as separate IDL definitions that get referenced by other IDL definitions — I guess the important point is that browser engines aren’t required to implement dictionaries that way.

That is, if a browser engine doesn’t internally implement a dictionary as separate IDL definition, but instead just puts the dictionary members directly into the method as the method arguments such that the observable effect is the same, then that browser engine’s implementation is still 100% conforming as far as the normative requirements of the spec go.

And the same could be said if a browser engine chooses to internally use a completely different name for a dictionary than the name used for that dictionary in the spec.

Or a spec could even change the name of a dictionary, and all the implementations which had already implemented it by the previous name would still remain conformant to the spec.

So the dictionary names are basically arbitrary, in that they can be completely changed at any time without breaking web compat, because they aren’t observable to web content — that is, not observable to frontend JavaScript code; and that’s intentionally so, because spec authors really have never made any effort to follow consistent naming conventions for dictionaries, due to the fact the dictionary names aren’t exposed or observable by web developers.

Given all the above, I really don’t think we have any compelling reason to represent dictionaries as their own entries in BCD.

[domenic]

Strong +1. I especially want to emphasize this point

In fact I think it could reasonably said that having dictionaries documented separately in MDN creates an unnecessary level of indirection that’s an inconvenience for web developers — because web developers only care, for example, what parameters a particular method actually has, and they want to see that information at point of use, rather than needing to navigate over to yet another separate MDN article to find the information they need.

which I've found to be particularly painful when browsing MDN.

[saschanaz]

I have two opinions:

• We don't need a separate MDN page for each dictionary, as others said above.
• But for Use BCD to autoremove unimplemented features microsoft/TypeScript-DOM-lib-generator#915 dictionary entries in BCD can be helpful to detect support status for them.

Ideally we could move dictionary entries into a separate dictionary/ directory, add a way to reference it inside api/, and make MDN show a merged table.

[foolip]

Another +1 to what @sideshowbarker said. The names of dictionaries are indeed invisible to web developers, and don't even show up in error messages about missing required members, at least not in Chromium.

There's some precedence for subfeatures to represent dictionary member support for specific methods:
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Browser_compatibility
https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener#Browser_compatibility

@vinyldarkscratch and I discussed a bit and we both think there's previous discussion about organizing the api/ directory, but can't find it. I did find #3496 about adding a type attribute to each API entry however, which is something I've often wanted.

@saschanaz a big unknown for me here is how TypeScript handled dictionaries and uses BCD. Are the dictionaries derived from Web IDL (webref or similar) and then BCD is used only to determine if they're supported or not? Would it be possible to handle a situation where a dictionary member was supported in one context but not another?

[saschanaz]

Are the dictionaries derived from Web IDL (webref or similar) and then BCD is used only to determine if they're supported or not?

Exactly.

Would it be possible to handle a situation where a dictionary member was supported in one context but not another?

Not with the current setup, as it does not create separate dictionaries for each context but just shares the same definition.

[foolip]

Thanks @saschanaz! It sounds like the requirement for https://github.com/microsoft/TypeScript-DOM-lib-generator is to be able to find, starting with the sum of all Web IDL and a specific dictionary definition, the entry or entries in BCD that say whether each dictionary member is supported or not. Having the dictionaries (with matching names) in BCD is the most straightforward way to achieve this, and if we change this we should figure out if the mapping is still easy enough. For dictionaries used as return types especially, I imagine BCD would need a bunch of extra information that currently isn't represented at all.

I am curious though, given how few dictionaries are currently in BCD and that their data is hard to keep up-to-date, does TypeScript-DOM-lib-generator currently get much value out of BCD on this front?

[saschanaz]

I am curious though, given how few dictionaries are currently in BCD and that their data is hard to keep up-to-date, does TypeScript-DOM-lib-generator currently get much value out of BCD on this front?

Not too much, and I just haven't tried dictionaries. I don't expect BCD to include every dictionary in the IDL world, probably return type dictionaries would be sufficient for now.

[gsnedders]

@ddbeck effectively documented something for this in #10509:

For properties of parameter objects, use a subfeature named paramname_prop_parameter with description text <code>paramname.prop</code> parameter, where paramname is the name of the parameter object and prop is the name of the property.

[foolip]

Indeed, I've been following that guideline and it's fairly complete for what I've come across. @ddbeck do you think we should treat this issue as resolved in favor of deleting all dictionaries, or at this point merely allow their deletion?

[ddbeck]

do you think we should treat this issue as resolved in favor of deleting all dictionaries, or at this point merely allow their deletion?

Since we've removed many dictionaries already, I'd say we've de facto favored deleting all dictionaries. As for closing this issue, we could either use this to track the disposition of any remaining dictionaries, or open a new issue to cover completing the removal. I'm not sure what's more useful in this case.

[queengooborg]

I'm leaning towards opening a new issue for tracking the remaining dictionaries! Funny thing is I was actually planning to tackle their removal just now, and am putting together the list!

Update: it looks like there's an issue already open documenting removal of dictionaries, among other non-interface features! #6810

[ddbeck]

OK, if #6810 is tracking the work, then we can close this one now.

Let the record show: BCD should not record data about dictionaries, in the abstract. See the guideline added by #10509 for covering dictionaries as they're actually used by web developers.