1759053 - Add documentation for ObservableArray

Status: NEW

(Core :: DOM: Bindings (WebIDL), task)

Description

[Edgar Chen [:edgar]]

Add some documentation to https://searchfox.org/mozilla-central/source/dom/docs/webIdlBindings/index.md (documenting the hooks used to mutate the array etc)

Comment 1

[Rob Wu [:robwu]]

I'm trying to understand the ObservableArray implementation in order to see how difficult it is to support Xrays for it (bug 1751346) and am looking up patches to figure out how it works architecturally.

The implementation was added in bug 1683281. The shape of the slots is described by Part 5: Generate binding code for ObservableArray type ( https://phabricator.services.mozilla.com/D112280 ):

The highlevel architecture:

• Each observable array attribute has corresponding ES proxy exotic object stored in DOM reflector's reserved slot. It use the ObservableArrayProxyHandler as proxy handler which implements the behaviour defined in the spec.
• Each observable array exotic objects has 2 reserved slots:
  • one is to store the raw pointer of the interface, it is cleaned up when the DOM reflector is finalized. It is used to run the SetAlgorithm and DeleteAlgorithm defined in the spec.
  • one is to store the backing list used to store the indexed value. The additional properties are stored in the proxy target instead.

I don't have a full picture yet, but figured that adding some context on this documentation bug is better than having no context at all.