MDL-63714 javascript: Improve docs for pendingjs

diff --git a/lib/javascript-static.js b/lib/javascript-static.js
index 444aab5..a4296ee 100644 (file)
--- a/lib/javascript-static.js
+++ b/lib/javascript-static.js
@@ -653,16 +653,22 @@ M.util.complete_js = [];
 
 /**
  * Register any long running javascript code with a unique identifier.
- * Should be followed with a call to js_complete with a matching
- * idenfitier when the code is complete. May also be called with no arguments
- * to test if there is any js calls pending. This is relied on by behat so that
- * it can wait for all pending updates before interacting with a page.
- * @param String uniqid - optional, if provided,
- *                        registers this identifier until js_complete is called.
- * @return boolean - True if there is any pending js.
+ * This is used to ensure that Behat steps do not continue with interactions until the page finishes loading.
+ *
+ * All calls to M.util.js_pending _must_ be followed by a subsequent call to M.util.js_complete with the same exact
+ * uniqid.
+ *
+ * This function may also be called with no arguments to test if there is any js calls pending.
+ *
+ * The uniqid specified may be any Object, including Number, String, or actual Object; however please note that the
+ * paired js_complete function performs a strict search for the key specified. As such, if using an Object, the exact
+ * Object must be passed into both functions.
+ *
+ * @param   {Mixed}     uniqid Register long-running code against the supplied identifier
+ * @return  {Number}    Number of pending items
  */
 M.util.js_pending = function(uniqid) {
-    if (uniqid !== false) {
+    if (typeof uniqid !== 'undefined') {
         M.util.pending_js.push(uniqid);
     }
 
@@ -690,11 +696,12 @@ YUI.add('moodle-core-io', function(Y) {
 });
 
 /**
- * Unregister any long running javascript code by unique identifier.
- * This function should form a matching pair with js_pending
+ * Unregister some long running javascript code using the unique identifier specified in M.util.js_pending.
+ *
+ * This function must be matched with an identical call to M.util.js_pending.
  *
- * @param String uniqid - required, unregisters this identifier
- * @return boolean - True if there is any pending js.
+ * @param   {Mixed}     uniqid Register long-running code against the supplied identifier
+ * @return  {Number}    Number of pending items remaining after removing this item
  */
 M.util.js_complete = function(uniqid) {
     // Use the Y.Array.indexOf instead of the native because some older browsers do not support
@@ -702,6 +709,8 @@ M.util.js_complete = function(uniqid) {
     var index = Y.Array.indexOf(M.util.pending_js, uniqid);
     if (index >= 0) {
         M.util.complete_js.push(M.util.pending_js.splice(index, 1));
+    } else {
+        window.console.log("Unable to locate key for js_complete call", uniqid);
     }
 
     return M.util.pending_js.length;