diff options
| -rw-r--r-- | src/ng/q.js | 20 |
1 files changed, 15 insertions, 5 deletions
diff --git a/src/ng/q.js b/src/ng/q.js index 6c4d3f5f..a9eed738 100644 --- a/src/ng/q.js +++ b/src/ng/q.js @@ -26,6 +26,8 @@ * // since this fn executes async in a future turn of the event loop, we need to wrap * // our code into an $apply call so that the model changes are properly observed. * scope.$apply(function() { + * deferred.notify('About to greet ' + name + '.'); + * * if (okToGreet(name)) { * deferred.resolve('Hello, ' + name + '!'); * } else { @@ -42,6 +44,8 @@ * alert('Success: ' + greeting); * }, function(reason) { * alert('Failed: ' + reason); + * }, function(update) { + * alert('Got notification: ' + update); * }); * </pre> * @@ -60,7 +64,8 @@ * A new instance of deferred is constructed by calling `$q.defer()`. * * The purpose of the deferred object is to expose the associated Promise instance as well as APIs - * that can be used for signaling the successful or unsuccessful completion of the task. + * that can be used for signaling the successful or unsuccessful completion, as well as the status + * of the task. * * **Methods** * @@ -68,6 +73,8 @@ * constructed via `$q.reject`, the promise will be rejected instead. * - `reject(reason)` – rejects the derived promise with the `reason`. This is equivalent to * resolving it with a rejection constructed via `$q.reject`. + * - `notify(value)` - provides updates on the status of the promises execution. This may be called + * multiple times before the promise is either resolved or rejected. * * **Properties** * @@ -84,12 +91,15 @@ * * **Methods** * - * - `then(successCallback, errorCallback)` – regardless of when the promise was or will be resolved - * or rejected, `then` calls one of the success or error callbacks asynchronously as soon as the result - * is available. The callbacks are called with a single argument: the result or rejection reason. + * - `then(successCallback, errorCallback, notifyCallback)` – regardless of when the promise was or + * will be resolved or rejected, `then` calls one of the success or error callbacks asynchronously + * as soon as the result is available. The callbacks are called with a single argument: the result + * or rejection reason. Additionally, the notify callback may be called zero or more times to + * provide a progress indication, before the promise is resolved or rejected. * * This method *returns a new promise* which is resolved or rejected via the return value of the - * `successCallback` or `errorCallback`. + * `successCallback`, `errorCallback`. It also notifies via the return value of the `notifyCallback` + * method. The promise can not be resolved or rejected from the notifyCallback method. * * - `catch(errorCallback)` – shorthand for `promise.then(null, errorCallback)` * |