dom_observer.js in testable-0.4.0

- old
+ new

@@ -1,10 +1,37 @@
-// WebDriver arguments
-var element = arguments[0];
-var delay = arguments[1] * 1000;
+/*
+This functionality will only work for browsers that support it.
+See: http://caniuse.com/#feat=mutationobserver
+*/
+
+// WebDriver arguments, which are passed to the MutationObserver.
+var element  = arguments[0];
+var delay    = arguments[1] * 1000;
 var callback = arguments[2];
 
+/*
+The two functions below are similar in what they are doing. Both are
+disconneting the observer. Both are also invoking WebDriver's callback
+function.
+
+notStartedUpdating passes true to the callback, which indicates that the
+DOM has not yet begun updating.
+
+startedUpdating passes false to the callback, which indicates that the
+DOM has begun updating.
+
+The disconnect is important. You only want to be listening (observing) for the
+period required, removing the listeners when done. Since there be many DOM
+operations, you want to disconnet when there is interaction with the page by
+the automated scripts.
+
+When observing a node for changes, the callback will not be fired until the
+DOM has finished changing. That is the only granularity that is required for
+the Cogent implementation. What specific events occurred is not important
+because the goal is not to conditionally respond to them; rather just to know
+when the process has completed.
+*/
 var notStartedUpdating = function() {
     return setTimeout(function() {
         observer.disconnect();
         callback(true);
     }, 1000);
@@ -14,10 +41,37 @@
     clearTimeout(notStartedUpdating);
     observer.disconnect();
     callback(false);
 };
 
-// Observer
+/*
+Mutation Observer
+The W3C DOM4 specification initially introduced mutation observers as a
+replacement for the deprecated mutation events.
+
+The MutationObserver is a JavaScript native object that allows for observing
+a change on any node-like DOM Element. "Mutation" means the addition or the
+removal of a node as well as changes to the node's attribute and data.
+
+The general approach is to create a MutationObserver object with a defined
+callback function. The function will execute on every mutation observed by
+the MutationObserver. The MutationObserver must be bound to a target, which
+for Cogent would mean the element whose context it is being called upon.
+
+A MutationObserver can be provided with a set of options, which indicate
+what kind of events should be observed.
+
+The childList option checks for additions and removals of the target node's
+child elements, including text nodes. This is basically looking for any
+nodes added or removed from documentElement.
+
+The subtree option checks for mutations to the target as well the target's
+descendants. So that means every child node of documentElement.
+
+The attribute option checks for mutations to the target's attributes.
+
+The characterData option checks for mutations to the target's data.
+*/
 var observer = new MutationObserver(startedUpdating);
 var config = { attributes: true, childList: true, characterData: true, subtree: true };
 observer.observe(element, config);
 
 var notStartedUpdating = notStartedUpdating();