Compose: Documentation: Document withGlobalEvents

[aduth]

This pull request seeks to add missing documentation for the withGlobalEvents higher-order component creator.

Testing Instructions:

Verify by rendered output of "Files changed" tab that produced documentation is sensible.

There are only documentation changes. Thus, there is no expected impact on application runtime.

[ellatrix]

Interesting. Isn't that a built in feature of addEventListener to bind once at most?

The event listener list will not contain multiple event listeners with equal type, callback, and capture, as add an event listener prevents that.

https://dom.spec.whatwg.org/#dom-eventtarget-addeventlistener

[aduth]

The key words there being "equal [..] callback". Since function() {} !== function() {}, it's not reused.

Try in the console, for example:

[ ...Array( 5 ) ].forEach( ( v, i ) => document.addEventListener( 'click', () => console.log( 'click' + i ) ) )

[aduth]

Interesting. Isn't that a built in feature of addEventListener to bind once at most?

While it's not really relevant for change here, the question does get me wondering whether it really matters to consolidate to a single event handler. I'm trying to recall from the original implementation (#5730) whether I'd thought this was some sort of performance enhancement (i.e. one 'scroll' handler on the window rather than one for every component) and if that was the case, whether there's actually any truth to the consolidation being an optimization. I might expect a browser with its low-level language code could iterate to invoke individual callbacks of addEventListener faster than we could iterate to invoke the Listener callbacks here in JavaScript.