mediawiki.requestIdleCallback: Improve documentation

* Explain basic logic.
* Document the 'options.timeout' parameter of the native interface.
  The fallback shim ignores this parameter because it always executes
  callbacks using setTimeout(,1), which is before any timeout would
  expire. The native requestIdleCallback is smarter about scheduling
  callbacks at moments in time when no other priority things happen,
  at which point the timeout helps inform how long to wait at most
  for an idle period to naturally occur.

Change-Id: I45126b875547f64ec8b450a264b250260c41084c

diff --git a/resources/src/mediawiki/mediawiki.requestIdleCallback.js b/resources/src/mediawiki/mediawiki.requestIdleCallback.js
index b58cb69..d414232 100644 (file)
--- a/resources/src/mediawiki/mediawiki.requestIdleCallback.js
+++ b/resources/src/mediawiki/mediawiki.requestIdleCallback.js
@@ -1,8 +1,3 @@
-/*!
- * An interface for scheduling background tasks.
- *
- * Loosely based on https://w3c.github.io/requestidlecallback/
- */
 ( function ( mw ) {
        var maxBusy = 50;
 
@@ -21,8 +16,32 @@
        /**
         * Schedule a deferred task to run in the background.
         *
+        * This allows code to perform tasks in the main thread without impacting
+        * time-critical operations such as animations and response to input events.
+        *
+        * Basic logic is as follows:
+        *
+        * - User input event should be acknowledged within 100ms per [RAIL].
+        * - Idle work should be grouped in blocks of upto 50ms so that enough time
+        *   remains for the event handler to execute and any rendering to take place.
+        * - Whenever a native event happens (e.g. user input), the deadline for any
+        *   running idle callback drops to 0.
+        * - As long as the deadline is non-zero, other callbacks pending may be
+        *   executed in the same idle period.
+        *
+        * See also:
+        *
+        * - <https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback>
+        * - <https://w3c.github.io/requestidlecallback/>
+        * - <https://developers.google.com/web/updates/2015/08/using-requestidlecallback>
+        * [RAIL]: https://developers.google.com/web/fundamentals/performance/rail
+        *
         * @member mw
         * @param {Function} callback
+        * @param {Object} [options]
+        * @param {number} [options.timeout] If set, the callback will be scheduled for
+        *  immediate execution after this amount of time (in milliseconds) if it didn't run
+        *  by that time.
         */
        mw.requestIdleCallback = mw.requestIdleCallbackInternal;
        /*