making fixes for wolenetz review comments

[chrisdavidmills]

Description

This PR makes fixes for the review comments by @wolenetz included in #22327.

Specifically, I have:

• Updated the srcObject page to fix the note at the top, making it accurate for the current situation
• Fixed the code examples and descriptions as suggested, in all pages that they appear.
• Made it clear that handle is only accessible from dedicated workers.
• Made other assorted fixes to the text.
• Verified that the "available in web workers" links are working ok (yes, these are just broken in the previews, as only previews of changed pages are generated)

Motivation

Additional details

Related issues and pull requests

Fixes #22327

[github-actions]

Preview URLs

• /en-US/docs/Web/API/HTMLMediaElement/srcObject
• /en-US/docs/Web/API/MediaSource/handle
• /en-US/docs/Web/API/MediaSourceHandle
• /en-US/docs/Web/API/MediaSource
• /en-US/docs/Web/API/Media_Source_Extensions_API

Flaws (7)

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

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

• macros:
  • /en-US/docs/Web/API/MediaSource/sourceclose_event does not exist
  • /en-US/docs/Web/API/MediaSource/sourceended_event does not exist
  • /en-US/docs/Web/API/MediaSource/sourceopen_event does not exist
• bad_bcd_links:
  • no explanation!
  • no explanation!
  • no explanation!

---

URL: /en-US/docs/Web/API/Media_Source_Extensions_API
Title: Media Source API
Flaw count: 1

• macros:
  • /en-US/docs/Web/API/TextTrack/sourceBuffer does not exist

(this comment was updated 2022-11-18 07:38:00.143534)

[wolenetz]

Looks pretty good. Thank you for addressing the feedback. While the number of nits I have seems large on this PR, they are mostly duplicates due to the example usage text is duplicated so much (aside: is there a way to inline a shared example set of text, or is this copy/paste of example usage text/script unfortunately required?)

Note, I can only "comment", not "request changes" in the review dialog, but please do address these nits. Thanks again for your work!

[chrisdavidmills]

Thanks @wolenetz ! I think I fixed 'em all.

is there a way to inline a shared example set of text, or is this copy/paste of example usage text/script unfortunately required?

It would be nice to have a robust include/component type system to do this, but unfortunately, MDN doesn't really have one right now. I think there is still a macro in existence that allows you to include a section from one page on another, but IIRC it is somewhat fragile.

[wolenetz]

I should have mentioned this previously - my apologies. It might be a good idea to also mention that this handle getter will always return the same MediaSourceHandle instance specific to the dedicated worker MediaSource instance. In particular, if the handle has already been transferred to the main thread using postMessage, the handle instance in the worker is technically detached and no longer can be transferred again. --- or is this too much detail for MDN? It is definitely in the MSE spec, in the Chrome implementation as of 108, and also in the interop web-platform-test suite for MSE.

[chrisdavidmills]

This isn't too much detail — this is a really useful bit of information to include. I've included a note to explain this on both the MediaSourceHandle and MediaSource.handle pages.

[wolenetz]

It would be nice to have a robust include/component type system to do this, but unfortunately, MDN doesn't really have one right now. I think there is still a macro in existence that allows you to include a section from one page on another, but IIRC it is somewhat fragile.

Ack.

[wolenetz]

Looks good to me (the comment I made today about the specifics around the [SameObject] semantic can be addressed in a later PR or not at all if you deem that to be too much detail for the handle getter's MDN documentation.)