Merge d80f196 into 9fe4e6b

lib/index.js

@@ -544,11 +544,29 @@ class Generator extends EventEmitter {
       debug(`Running ${namespace}#${methodName}`);
       self.emit(`method:${methodName}`);
 
-      runAsync(function() {
+      const wrappedFunction = function() {
+        /* 'this' context is provided by runAsync. It contains only async().
+         * Set generator's async with the one provided by runAsync.
+         * async() simulates an async function by creating a callback.
+         */
         self.async = () => this.async();
         self.runningState = { namespace, queueName, methodName };
         return method.apply(self, self.args);
-      })()
+      };
+
+      /* RunAsync creates a promise and executes wrappedFunction.
+       * It supports promises/async and sync functions.
+       * - Promises/async: forward resolve/reject from the runAsync promise to the
+       *   promise returned by the wrappedFunction.
+       * - Sync functions: resolves with the returned value.
+       *   Can be a promise for chaining
+       * - Sync functions with callback (done = this.async()) calls:
+       *   Reject with done() first argument
+       *   Resolve with done() second argument
+       * - Callback must called when 'async()' was called inside a sync function.
+       * - Callback is ignored when 'async()' was called inside a async function.
+       */
+      runAsync(wrappedFunction)()
         .then(function() {
           delete self.runningState;
           completed();