Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Maplike and Setlike objects in Map and Set #27160

Merged
merged 14 commits into from
Jun 16, 2023

Conversation

hamishwillee
Copy link
Collaborator

These glossary entries are designed to make it easier to talk about setlike and maplike objects, and what APIs might be present in both readonly and read/write versions.

I've listed the items I could find in both types in the appropriate entries.

I also added a comment about the IDL.

Follows on from comment in #27028 (comment)

FYI @wbamberg

@hamishwillee hamishwillee requested review from a team as code owners June 6, 2023 05:21
@hamishwillee hamishwillee requested review from wbamberg and removed request for a team June 6, 2023 05:21
@github-actions github-actions bot added Content:Glossary Glossary entries Content:WebAPI Web API docs labels Jun 6, 2023
@github-actions
Copy link
Contributor

github-actions bot commented Jun 6, 2023

Preview URLs (14 pages)
Flaws (16)

Note! 9 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/RTCStatsReport
Title: RTCStatsReport
Flaw count: 6

  • macros:
    • /en-US/docs/Web/API/RTCCertificateStats does not exist
    • /en-US/docs/Web/API/RTCCodecStats does not exist
    • /en-US/docs/Web/API/RTCDataChannelStats does not exist
    • /en-US/docs/Web/API/RTCVideoSourceStats does not exist
    • /en-US/docs/Web/API/RTCRemoteInboundRtpStreamStats does not exist
    • and 1 more flaws omitted

URL: /en-US/docs/Web/API/Highlight
Title: Highlight
Flaw count: 1

  • macros:
    • wrong xref macro used (consider changing which macro you use)

URL: /en-US/docs/Web/API/AudioParamMap
Title: AudioParamMap
Flaw count: 6

  • macros:
    • /en-US/docs/Web/API/AudioParamMap/size does not exist
    • /en-US/docs/Web/API/AudioParamMap/entries does not exist
    • /en-US/docs/Web/API/AudioParamMap/forEach does not exist
    • /en-US/docs/Web/API/AudioParamMap/has does not exist
    • /en-US/docs/Web/API/AudioParamMap/keys does not exist
    • and 1 more flaws omitted

URL: /en-US/docs/Web/API/HighlightRegistry
Title: HighlightRegistry
Flaw count: 2

  • macros:
    • wrong xref macro used (consider changing which macro you use)
    • /en-US/docs/Web/API/CSS/highlights redirects to /en-US/docs/Web/API/CSS/highlights_static

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
Title: Set
Flaw count: 1

  • broken_links:
    • Link points to the page it's already on

(comment last updated: 2023-06-16 15:08:29)

Copy link
Member

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Casual reviews

files/en-us/glossary/maplike_object/index.md Outdated Show resolved Hide resolved
files/en-us/glossary/setlike_object/index.md Outdated Show resolved Hide resolved
files/en-us/glossary/setlike_object/index.md Outdated Show resolved Hide resolved
Copy link
Member

@estelle estelle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These "definitions" are IDL definitions, not glossary terms. Glossary entries define terms. This content is better suited for /en-US/docs/Web/API/ or Web/JavaScript/Reference under the official name of the IDL/spec, with a summary in the glossary pointing to that documentation and example implementations within MDN and in the wild.

@Josh-Cena
Copy link
Member

I am open to adding them as a subsection under the Map and Set pages' description section.

@hamishwillee
Copy link
Collaborator Author

These "definitions" are IDL definitions, not glossary terms. Glossary entries define terms. This content is better suited for /en-US/docs/Web/API/ or Web/JavaScript/Reference under the official name of the IDL/spec, with a summary in the glossary pointing to that documentation and example implementations within MDN and in the wild.

Thanks. I don't disagree. Though note, this is the same approach as transferrable objects and serializable objects in the glossary.

I quite like the idea of having these as sections in Map and Set. @wbamberg any comments?

@Josh-Cena
Copy link
Member

this is the same approach as transferrable objects and serializable objects in the glossary.

https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects is now a Web API page as well.

@estelle
Copy link
Member

estelle commented Jun 7, 2023

Thanks. I don't disagree. Though note, this is the same approach as transferrable objects and serializable objects in the glossary.

There are a few glossary items, including these, that need to be revisited and de-glossary-ified (Base 64 is another one). Now that transferable objects has an API page, it will be easier to do. Let's not add to that. I also quite like the idea of having these as sections in Map and Set as @Josh-Cena suggested

@hamishwillee
Copy link
Collaborator Author

I do too. I'll looking to moving this stuff either Friday or next week, firefox-project work permitting.

@wbamberg
Copy link
Collaborator

wbamberg commented Jun 9, 2023

We talked about this in the SC meeting on Wednesday. I had forgotten about transferable and serializable, and agree that they're the same kind of thing. I agree that glossary is not a great place to put pages like this, and am happy FWIW for them to go in the JS docs, for now.

But I think we need a proper home for pages like this, that cover general categories in Web/API. In the SC meeting we talked about having a project in H2 to figure out a proper home for them.

@hamishwillee hamishwillee requested a review from a team as a code owner June 9, 2023 03:03
@github-actions github-actions bot added Content:JS JavaScript docs and removed Content:Glossary Glossary entries labels Jun 9, 2023
@hamishwillee
Copy link
Collaborator Author

@wbamberg Thanks for the information. That all makes sense to me, though for this particular case adding this to Map/Set feels like a good fit. The only problem is that it is cleaner not to mix JavaScript and WebAPI.

@Josh-Cena I have moved this to the Map and Set topics so good time for a new review.

@hamishwillee hamishwillee changed the title Glossary - new entries for Maplike and Setlike objects Maplike and Setlike objects in Map and Set Jun 9, 2023
@hamishwillee
Copy link
Collaborator Author

@Josh-Cena @wbamberg Would appreciate a review on this when you have time. I have updated the titles to "X-like browser APIs" in the respective docs to reflect upcoming JavaScript Set-like objects.

files/en-us/web/api/xranchorset/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/highlightregistry/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/highlight/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/gpusupportedfeatures/index.md Outdated Show resolved Hide resolved
files/en-us/web/api/gpusupportedfeatures/index.md Outdated Show resolved Hide resolved
Copy link
Member

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Little nits. @wbamberg said about making a dedicated page for web IDL entities (IIUC); I don't have strong opinions but that does sound more scalable.

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Copy link
Member

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's pick one. I don't have preferences

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
@hamishwillee
Copy link
Collaborator Author

Thanks. Works for me.

@hamishwillee
Copy link
Collaborator Author

Can we merge this?

@Josh-Cena
Copy link
Member

Oops, @hamishwillee—you were supposed to pick one suggestion (indent by 2 or 4)...

@hamishwillee
Copy link
Collaborator Author

@Josh-Cena I guess I should learn to read - saw that as fixes to two cases. I have decided on "2 spaces". Fixed

Copy link
Member

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am approving and will merge in the next few days unless @wbamberg gives a -1 on the current approach.

files/en-us/web/api/rtcstatsreport/index.md Outdated Show resolved Hide resolved
Copy link
Collaborator

@wbamberg wbamberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Elchi3 filed openwebdocs/project#159 which might revisit things, but this is fine. Thank you @hamishwillee !

@Josh-Cena Josh-Cena merged commit 8dcea68 into mdn:main Jun 16, 2023
@hamishwillee hamishwillee deleted the maplike_setlike branch June 18, 2023 23:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content:JS JavaScript docs Content:WebAPI Web API docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants