1783814 - Add documentation for SandboxOptions

Status: RESOLVED FIXED

(Core :: XPConnect, task)

Description

[Julian Descottes [:jdescottes]]

The SandboxOptions which can be used with Cu.Sandbox are not documented in tree at the moment, but they used to be documented, on MDN (see backup at https://udn.realityripple.com/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.Sandbox).

We should add the documentation in tree to keep it up to date and avoid losing the information.

Not clear what is the best spot to add the documentation though.

I can see a SandboxOptions defined at https://searchfox.org/mozilla-central/rev/c0bed29d643393af6ebe77aa31455f283f169202/js/xpconnect/src/xpcprivate.h#2318 but but it is not using the property names exposed to Cu.Sandbox (eg sandboxPrototype is proto there). Otherwise there is also https://searchfox.org/mozilla-central/rev/c0bed29d643393af6ebe77aa31455f283f169202/js/xpconnect/src/Sandbox.cpp#1925-1943.

But overall I haven't found an IDL which would be a good spot to add this documentation for now. I think the only mention of the Sandbox in IDLs is https://searchfox.org/mozilla-central/rev/c0bed29d643393af6ebe77aa31455f283f169202/js/xpconnect/idl/xpccomponents.idl#81-87

So I would say the spot which makes the most sense to add the documentation would be the SandboxOptions::Parse definition, because at least we have all the options listed using the property names exposed to Chrome JS. I will go ahead and add the documentation here for now, but maybe we want to have more substantial changes so that the options can be documented in the IDL.

Comment 1

[Kris Maglione [:kmag]]

I'd lean towards just putting it above the Cu.Sandbox definition in xpccomponents.idl. I know it isn't defined as a method there and there isn't an explicit SandboxOptions type, but that's where people are going to look for it, and we don't have a doc comment parser for IDL anyway.

Comment 2

[Julian Descottes [:jdescottes]]

(In reply to Kris Maglione [:kmag] from comment #1)

I'd lean towards just putting it above the Cu.Sandbox definition in xpccomponents.idl. I know it isn't defined as a method there and there isn't an explicit SandboxOptions type, but that's where people are going to look for it, and we don't have a doc comment parser for IDL anyway.

Sounds good, will do that.

Comment 3

[Julian Descottes [:jdescottes]]

Attachment: Bug 1783814 - Add documentation for SandboxOptions previously documented on MDN

This only ports documentation for options which used to be documented on MDN.
Since then new sandbox options have been added, I will try to add documentation for them in a second changeset

Comment 4

[Julian Descottes [:jdescottes]]

Attachment: Bug 1783814 - Add documentation for remaining SandboxOptions

Depends on D154260

Add documentation for

• allowWaivers
• discardSource
• forceSecureContext
• freshCompartment
• invisibleToDebugger
• isWebExtensionContentScript
• metadata
• originAttributes
• userContextId

Comment 5

[Julian Descottes [:jdescottes]]

Added points + whiteboard flags as we're just tracking this as part of our work related to webdriver bidi, but let me know if that's an issue for any internal process you might have.

Comment 6

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/a8597106ee97
Add documentation for SandboxOptions previously documented on MDN r=kmag
https://hg.mozilla.org/integration/autoland/rev/b8729fd13ff5
Add documentation for remaining SandboxOptions r=kmag

Comment 7

[Cosmin Sabou [:CosminS]]

https://hg.mozilla.org/mozilla-central/rev/a8597106ee97
https://hg.mozilla.org/mozilla-central/rev/b8729fd13ff5