justifying use of nextTick

src/courier/courier.js

@@ -177,6 +177,9 @@ define(function (require) {
   // force a fetch of all datasources right now, optionally filter by type
   Courier.prototype.fetch = function (onlyType) {
     var courier = this;
+    // ensure that onFetch functions always run after the tick
+    // so that users can will be able to listen after or before the call to
+    // fetch and always get the same behavior (even if the onFetch runs synchronously)
     nextTick(function () {
       _.forOwn(onFetch, function (fn, type) {
         if (onlyType && onlyType !== type) return;

src/courier/data_source/doc.js

@@ -77,6 +77,7 @@ define(function (require) {
       /* jshint eqeqeq: false */
       return (!ref.fetchCount || !ref.version || ref.version != storedVersion);
     });
+    // callbacks should always be called async
     nextTick(cb, void 0, invalid);
   };
 

src/courier/mapper.js

@@ -37,7 +37,8 @@ define(function (require) {
      */
     this.getFields = function (dataSource, callback) {
       if (self.getFieldsFromObject(dataSource)) {
-        // If we already have the fields in our object, use that.
+        // If we already have the fields in our object, use that, but
+        // make sure we stay async
         nextTick(callback, void 0, self.getFieldsFromObject(dataSource));
       } else {
         // Otherwise, try to get fields from Elasticsearch cache

src/kibana/services/config.js

@@ -129,7 +129,7 @@ define(function (require) {
 
     function _notify(fns, cur, prev) {
       if ($rootScope.$$phase) {
-        // reschedule
+        // reschedule for next tick
         nextTick(_notify, fns, cur, prev);
         return;
       }

src/kibana/setup.js

@@ -91,6 +91,7 @@ define(function (require) {
         function checkForCurrentConfigDoc(es, done) {
           if (!kibanaIndexExists) return done();
           console.log('checking if migration is necessary: not implemented');
+          // callbacks should always be called async
           nextTick(done);
         }