Add documentation of component.utils exportFunction and cloneInto #30877

rebloor · 2023-12-08T18:06:59Z

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 · 2023-12-08T18:10:11Z

Preview URLs

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/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/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/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/cloneInto
Title: cloneInto()

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

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 👀)

(comment last updated: 2024-09-20 16:58:46)

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 · 2023-12-27T15:28:22Z

files/en-us/mozilla/add-ons/webextensions/api/components/index.md

+
+{{Compat}}
+
+> **Note:** This API is based on Chromium's [`chrome.devtools`](https://developer.chrome.com/docs/extensions/mv2/devtools/) API.


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

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

rebloor · 2023-12-27T23:20:32Z

@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 · 2023-12-28T04:05:13Z

@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 · 2023-12-28T18:07:00Z

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.

files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md

Rob--W · 2024-04-01T10:42:42Z

files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md

+
+## Examples
+
+This add-on script creates an object, clones it into the content window and makes it a property of the content window global:


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.

files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md

Co-authored-by: Rob Wu <[email protected]>

github-actions · 2024-07-26T03:29:19Z

This pull request has merge conflicts that must be resolved before it can be merged.

Rob--W

Thanks, this looks technically accurate. Could you address the nits and merge it?

Rob--W · 2024-09-20T06:42:38Z

files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md

+An Xray for an object refers to the original. Any changes to the argument made in the exported function affect the original object passed in. For example:
+
+```js
+// ad// privileged scope: for example, a content script


What is ad// doing here and in other places below?

No idea, some search/replace error, but a bit of head-scratcher.

files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md

files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md

Co-authored-by: Rob Wu <[email protected]>

…0877) * Add documentation of component.utils exportFunction and cloneInto * Resolved broken links, various edits * various edits * Various edits * Remove incorrect "based on" note * move exportFunction and cloneInto under Content_scripts * Cross-reference and slug corrections * Apply suggestions from review Co-authored-by: Rob Wu <[email protected]> * Further updates from feedback * casing fix * Apply suggestions from review Co-authored-by: Rob Wu <[email protected]> * Remove spurious ad// --------- Co-authored-by: Rob Wu <[email protected]>

Add documentation of component.utils exportFunction and cloneInto

6b440cc

rebloor added the Content:WebExt WebExtensions docs label Dec 8, 2023

rebloor requested a review from rpl December 8, 2023 18:06

rebloor self-assigned this Dec 8, 2023

rebloor added 4 commits December 10, 2023 06:06

Resolved broken links, various edits

48c8a78

various edits

50aec8a

Various edits

aa20e9f

Merge branch 'main' into components.utils

1fafc90

rebloor marked this pull request as ready for review December 12, 2023 01:45

rebloor requested a review from a team as a code owner December 12, 2023 01:45

Rob--W requested changes Dec 27, 2023

View reviewed changes

rebloor added 2 commits December 28, 2023 10:32

Merge branch 'main' into components.utils

11031e7

Merge branch 'main' into components.utils

c666642

Remove incorrect "based on" note

17c18b8

rebloor requested a review from Rob--W December 27, 2023 23:39

rebloor added 3 commits December 29, 2023 06:25

move exportFunction and cloneInto under Content_scripts

2c29e95

Cross-reference and slug corrections

7b321fa

Merge branch 'main' into components.utils

99b8384

Rob--W requested changes Apr 1, 2024

View reviewed changes

Apply suggestions from review

44465a5

Co-authored-by: Rob Wu <[email protected]>

github-actions bot added the size/m [PR only] 51-500 LoC changed label Apr 4, 2024

Further updates from feedback

32258a6

rebloor mentioned this pull request Apr 4, 2024

Add exportFunction and cloneInto mdn/browser-compat-data#22767

Merged

rebloor requested a review from Rob--W April 4, 2024 03:01

casing fix

e4b00ee

github-actions bot added the merge conflicts 🚧 [PR only] label Jul 26, 2024

Merge branch 'main' into components.utils

eab357c

github-actions bot removed the merge conflicts 🚧 [PR only] label Jul 26, 2024

Rob--W approved these changes Sep 20, 2024

View reviewed changes

rebloor and others added 2 commits September 21, 2024 04:52

Apply suggestions from review

3c7fbc5

Co-authored-by: Rob Wu <[email protected]>

Remove spurious ad//

c69abf5

rebloor merged commit 9f953f3 into mdn:main Sep 20, 2024
8 checks passed

rebloor deleted the components.utils branch September 20, 2024 17:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation of component.utils exportFunction and cloneInto #30877

Add documentation of component.utils exportFunction and cloneInto #30877

rebloor commented Dec 8, 2023 •

edited

Loading

github-actions bot commented Dec 8, 2023 •

edited

Loading

Rob--W left a comment

Rob--W Dec 27, 2023

rebloor Dec 27, 2023

rebloor commented Dec 27, 2023

Rob--W commented Dec 28, 2023

rebloor commented Dec 28, 2023

Rob--W left a comment

Rob--W Apr 1, 2024

github-actions bot commented Jul 26, 2024

Rob--W left a comment

Rob--W Sep 20, 2024

rebloor Sep 20, 2024


		{{Compat}}

		> Note: This API is based on Chromium's [`chrome.devtools`](https://developer.chrome.com/docs/extensions/mv2/devtools/) API.


		## Examples

		This add-on script creates an object, clones it into the content window and makes it a property of the content window global:

Add documentation of component.utils exportFunction and cloneInto #30877

Add documentation of component.utils exportFunction and cloneInto #30877

Conversation

rebloor commented Dec 8, 2023 • edited Loading

Description

Motivation

Related issues and pull requests

github-actions bot commented Dec 8, 2023 • edited Loading

Rob--W left a comment

Choose a reason for hiding this comment

Rob--W Dec 27, 2023

Choose a reason for hiding this comment

rebloor Dec 27, 2023

Choose a reason for hiding this comment

rebloor commented Dec 27, 2023

Rob--W commented Dec 28, 2023

rebloor commented Dec 28, 2023

Rob--W left a comment

Choose a reason for hiding this comment

Rob--W Apr 1, 2024

Choose a reason for hiding this comment

github-actions bot commented Jul 26, 2024

Rob--W left a comment

Choose a reason for hiding this comment

Rob--W Sep 20, 2024

Choose a reason for hiding this comment

rebloor Sep 20, 2024

Choose a reason for hiding this comment

rebloor commented Dec 8, 2023 •

edited

Loading

github-actions bot commented Dec 8, 2023 •

edited

Loading