API structure conventions: iterable, maplike, setlike

[Elchi3]

In the API reference documentation, there seems to be no convention how iterable/maplike/setlike are documented. I'd like to agree on a consistent approach.

Interfaces can be declared iterable, maplike, or setlike (see https://webidl.spec.whatwg.org/#idl-iterable and further) which means they will have the entries, forEach, keys, values, and [Symbol.iterator] properties on their prototype (and more if they are [readonly] maplike or setlike).

In BCD, whenever an interface is declared iterable/maplike/setlike, we add the relevant properties to the data. This gets done automatically using the @openwebdocs BCD collector most of the time anyways, so I think this is good as is. The only issue with the BCD entries is that we aren't sure which spec_urls to provide. We should fix that.

In mdn/content, there seem to be different approaches to how this gets documented and it would be good if we could make this consistent. There are at least these 5 different ways currently:

1. No documentation is provided at all (maybe because we lack a writing convention). Examples:
   • https://developer.mozilla.org/en-US/docs/Web/API/AudioParamMap
   • https://developer.mozilla.org/en-US/docs/Web/API/CSSNumericArray
   • https://developer.mozilla.org/en-US/docs/Web/API/MIDIInputMap
   • https://developer.mozilla.org/en-US/docs/Web/API/MIDIOutputMap
2. The methods get own sub pages but Symbol.iterator has no page. Examples:
   • https://developer.mozilla.org/en-US/docs/Web/API/CSSUnparsedValue
   • https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
   • https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList
   • https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet
   • https://developer.mozilla.org/en-US/docs/Web/API/FormData (forEach seems to be forgotten though)
   • https://developer.mozilla.org/en-US/docs/Web/API/Headers
   • https://developer.mozilla.org/en-US/docs/Web/API/Highlight
   • https://developer.mozilla.org/en-US/docs/Web/API/HighlightRegistry
   • https://developer.mozilla.org/en-US/docs/Web/API/KeyboardLayoutMap
   • https://developer.mozilla.org/en-US/docs/Web/API/MediaKeyStatusMap
   • https://developer.mozilla.org/en-US/docs/Web/API/StylePropertyMapReadOnly
   • https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
3. We point to the JavaScript documentation instead of creating own sub pages. Examples:
   • https://developer.mozilla.org/en-US/docs/Web/API/EventCounts
   • https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedFeatures
   • https://developer.mozilla.org/en-US/docs/Web/API/WGSLLanguageFeatures
   • https://developer.mozilla.org/en-US/docs/Web/API/XRAnchorSet
   • https://developer.mozilla.org/en-US/docs/Web/API/XRHand
   • https://developer.mozilla.org/en-US/docs/Web/API/XRInputSourceArray
4. Methods have sub pages and Symbol.iterator points to the JS Array page:
   • https://developer.mozilla.org/en-US/docs/Web/API/NodeList
5. Methods and Symbol.iterator all have their own sub pages:
   • https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport
   • (All JS pages do this (Array, Map, Set])

How would you prefer the interfaces document their iterable, maplike and setlike members?

[Josh-Cena]

See: mdn/content#6891

JS docs document every single member; I don't think that's going to change and I'm happy with the current structure conventions, so let's just discuss about Web APIs here.

Here's my personal suggestion:

1. No individual subpages for any member: has, forEach, etc.
2. On the landing page, in "Description", add a subsection called "[InterfaceName] is set-like" and put some boilerplate there, like "[InterfaceName] is a set-like browser API, which means bla bla bla, here's an example"
3. On the landing page, in the methods list, list these methods without linking them, like: "has(): makes the [InterfaceName] set-like. Returns whether the given [value] is in this [InterfaceName]. See [InterfaceName] is set-like (link to anchor) for more information."

...In other words, https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedFeatures is probably the closest to what I have in mind, except we shouldn't link to the JS methods but just link to the section on "set-like browser APIs" in the description.

[Rumyra]

Thanks for opening the conversation @Elchi3 !

I like 3. for maintenance costs - link to JS relevant documentation for each sub pages.

Also agree with @Josh-Cena 's point above - that set-like should be mentioned in the description, except I do like the way https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedFeatures does it with methods listed.

[Josh-Cena]

except I do like the way https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedFeatures does it with methods listed.

I agree they should be listed; I don't agree they should have their own subpages, or link to the Set method (as GPUSupportedFeatures is doing). They should be a dl with no links.

[Elchi3]

I also agree with the 3 points @Josh-Cena makes above except I also think linkage would be helpful.

So my thoughts:

1. No individual subpages for any member: has, forEach, etc.

Yes! +1
(And not only no subpages for the methods, but also no sub page for the symbols.)

2. On the landing page, in "Description", add a subsection called "[InterfaceName] is set-like" and put some boilerplate there, like "[InterfaceName] is a set-like browser API, which means bla bla bla, here's an example"

Yes! +1

On the landing page, in the methods list, list these methods without linking them, like: "has(): makes the [InterfaceName] set-like. Returns whether the given [value] is in this [InterfaceName]. See [InterfaceName] is set-like (link to anchor) for more information."

Almost +1. I think listing and linking the methods would be useful. Note that I wrote the page for XRHand and there I didn't link the methods in the <dt>, but provided a link to the relevant JS methods in the <dd>. So, I would be fine with linkage either in the <dt> directly or indirectly in the <dd> (hinting at the fact that you are leaving the interfaces' docs to see the "like"-interface). Either way I think some linkage to learn about each of these methods would be useful.

[Josh-Cena]

I'm also +1 to add a link in the dd, either to the "set-like" section on this page, or to the set method—both seem fine to me.

[Patrick-ring-motive]

I'm advocating for having separate pages for each of the built-in iterator types. The main reason is that they have conflicting compatibility tables and that is not at all clear on the single page. It could make organizing links to iterators more intuitive as a bonus.