mdn / mdn/browser-compat-data

Data guidelines for Web IDL iterable, setlike and maplike declarations

Open
#6,367 28 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

data:api docs:guidelines idle
Dominant language
JSON
Stars
5.8k
Forks
2.6k
Avg merge
1d 21h
Merged PRs (30d)
186

Description

Web IDL has some higher-level declarations that result in multiple things being exposed on an interface, and it would be great to have some data guidelines for how to represent these.

They are:

  • iterable<value_type> and iterable<key_type, value_type> result in @@iterator, entries, keys, values and forEach being exposed
  • async iterable<value_type> and async iterable<key_type, value_type> result in @@asyncIterator and some other things being exposed.
  • maplike<key_type, value_type> results in @@iterator, forEach, size, entries, keys, values, get, has, clear, delete and set being exposed
  • setlike<type> results in @@iterator, forEach, size, entries, keys, values, has, clear, delete and set being exposed

Apologies for inevitable mistakes in the above list.

There's already some inconsistency in how such things are represented in BCD. Here, as a "Support of for...of" entry:

https://github.com/mdn/browser-compat-data/blob/1ca3bd9afdea60d0cbeb6f270274ce3d492824d0/api/FormData.json#L102-L104

And here, as the @@iterator symbol and other entries:

https://github.com/mdn/browser-compat-data/blob/1ca3bd9afdea60d0cbeb6f270274ce3d492824d0/api/StylePropertyMapReadOnly.json#L434-L436

What should we do?

Opinion: As a reader of the StylePropertyMapReadOnly compat table it's not super useful to know that @@iterator is individually supported, it's more useful to know whether for (const [prop, val] of stylePropertyMap) { ... } will work. Knowing that entries could be more useful, however. Perhaps there should be a grouping of entries to reduce clutter?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading docs/data-guidelines.md and compare the FormData.json and StylePropertyMapReadOnly.json examples linked in the issue. Review the discussion to determine whether iterable, async iterable, maplike, and setlike declarations should be represented individually or as groups; done means the chosen guidance is documented and the affected examples are consistent.

Written by the indexing model from the issue text.

Assessment

Domain
data, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.