Add documentation of component.utils exportFunction and cloneInto

[rebloor]

Description

WIP to add component.utils exportFunction and cloneInto.

Todo:

• Finalize links in new pages
• Finalize location
• Add BCD
• Add internal references, e.g. from Sharing objects with page scripts

Motivation

These functions are references in Sharing objects with page scripts but not documented on MDN.

Related issues and pull requests

Fixes #29771
BCD mdn/browser-compat-data#22767

[github-actions]

Preview URLs

• /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneInto
• /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction
• /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts
• /en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts

Flaws (9)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts
Title: Content scripts
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneinto

---

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction
Title: exportFunction()
Flaw count: 2

• broken_links:
  • Anchor not lowercase
• bad_bcd_queries:
  • No BCD data for query: webextensions.api.contentScriptGlobalScope.exportFunction

---

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneInto
Title: cloneInto()
Flaw count: 5

• broken_links:
  • Can't resolve /en-US/docs/Mozilla/Add-ons/WebExtensions/API/Content_scripts/exportFunction
  • Anchor not lowercase
  • Anchor not lowercase
  • Can't resolve /en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction
• bad_bcd_queries:
  • No BCD data for query: webextensions.api.contentScriptGlobalScope.cloneInto

---

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts
Title: Share objects with page scripts
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneinto

External URLs (3)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction
Title: exportFunction()

• https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html (2 times) (Note! This may be a new URL 👀)
• https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html (3 times) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneInto
Title: cloneInto()

• https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-04-14 03:04:10)

[Rob--W]

The Components.utils API is an internal implementation detail of Firefox. Many years ago legacy Firefox add-ons had access to it, but WebExtensions don't. Their content scripts only have access to cloneInto/exportFunction, which exposes the same functionality.

There may be old links on the web pointing to these methods; if that is the concern I'd rather want redirects to the WebExtension-specific documentation.

If you need a place to host the method descriptions, I recommend to put them under Content_scripts/.

[Rob--W]

Looks like a mistake? This API is Firefox-only.

[rebloor]

@Rob--W Indeed - I'll remove it.

[rebloor]

@Rob--W I'm a little unclear about your feedback.

The Components.utils API is an internal implementation detail of Firefox. Many years ago legacy Firefox add-ons had access to it, but WebExtensions don't. Their content scripts only have access to cloneInto/exportFunction, which exposes the same functionality.

Just background?

There may be old links on the web pointing to these methods; if that is the concern I'd rather want redirects to the WebExtension-specific documentation.

The concern was, as per the issue: there is no documentation for exportFunction() and cloneInto() on MDN, however they are mentioned on Share objects with page scripts but only with examples but not syntax documentation or links to that documentation for the functions.

If you need a place to host the method descriptions, I recommend to put them under Content_scripts/.

Do you mean:

• Add-ons/WebExtensions/Content_scripts/components/utils/exportFunction
• Add-ons/WebExtensions/Content_scripts/components/utils/cloneInto

Or could we simplify to :

• Add-ons/WebExtensions/Content_scripts/exportFunction
• Add-ons/WebExtensions/Content_scripts/cloneInto

If we aren't following the usual API pattern and as neither the component nor utils page provides much information.

Or under the Share objects with page scripts?

[Rob--W]

@Rob--W I'm a little unclear about your feedback.

The Components.utils API is an internal implementation detail of Firefox. Many years ago legacy Firefox add-ons had access to it, but WebExtensions don't. Their content scripts only have access to cloneInto/exportFunction, which exposes the same functionality.

Just background?

No, not just background information. I am asserting that it does not make sense to add the articles for Components and Components.utils, because there is no way for extensions to use these today. The MDN articles for these existed in the past for the reasons I mentioned before, but were removed when Firefox-only (internal) APIs were removed from MDN. In case you are curious, this is how the documentation of Components.utils.exportFunction looked like in the past:

• 2015 (simply under /en-US/docs/Components.utils.exportFunction): https://web.archive.org/web/20150322003611/https://developer.mozilla.org/en-US/docs/Components.utils.exportFunction
• 2018 (page moved to /en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.exportFunction): https://web.archive.org/web/20180512135500/https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.exportFunction

The concern was, as per the issue: there is no documentation for exportFunction() and cloneInto() on MDN, however they are mentioned on Share objects with page scripts but only with examples but not syntax documentation or links to that documentation for the functions.

If you need a place to host the method descriptions, I recommend to put them under Content_scripts/.

Do you mean:

* Add-ons/WebExtensions/Content_scripts/components/utils/exportFunction

* Add-ons/WebExtensions/Content_scripts/components/utils/cloneInto

No.

Or could we simplify to :

* Add-ons/WebExtensions/Content_scripts/exportFunction

* Add-ons/WebExtensions/Content_scripts/cloneInto

Yes. That is what I meant.

[rebloor]

Thanks @Rob--W I've rearranged the content and added cross-references. Do you think we need to add the to functions to the navigation e.g.:

• Concepts
  • JavaScript APIs
  • Content scripts
  • exportFunction()
  • cloneInto()
  • …

(I'm not even sure it's possible, we don't do this with any of the other narrative content.)

If we're not considering these as part of the supported web extension API set, do you think we need browser compatibility data?

[Rob--W]

Here is partial feedback, please apply the general issues broadly to the whole PR and then request another review.

[Rob--W]

Can you replace all references of "add-on script" with "content script"? The original Components.utils.cloneInto method and its family of functions was documented in a general way because privileged code in add-ons, in general, could use this API anywhere. But in WebExtensions, only content scripts (and userScripts) can use it.