From e488b5a67e217d9d3cba133a16b25db5c9fe4dd9 Mon Sep 17 00:00:00 2001
From: Michal Charemza <michalcharemza@gmail.com>
Date: Sat, 7 Dec 2013 12:22:17 +0000
Subject: [PATCH] docs($q): add more detail and examples on chaining promises

Add examples on two ways of adding to chains of promises. The existing section mentions chaining,
but gives only a basic example and doesn't explain the different ways to defer resolution.
---
 src/ng/q.js | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/src/ng/q.js b/src/ng/q.js
index d559d4d38688..b11af042e009 100644
--- a/src/ng/q.js
+++ b/src/ng/q.js
@@ -132,6 +132,47 @@
  * promise (which will defer its resolution further), it is possible to pause/defer resolution of
  * the promises at any point in the chain. This makes it possible to implement powerful APIs like
  * $http's response interceptors.
+ * 
+ * ## Deferring the derived promise
+ *  
+ * If a promise is returned from the <em>successCallback</em> of <em>then</em>, this will defer
+ * the resolution of the derived promise.
+ *   
+ * <pre>
+ * var deferredA = $q.defer();
+ * var deferredB = $q.defer();
+ * var promiseA = deferredA.promise;
+ * var promiseB = deferredB.promise;
+ *
+ * var promiseC = promiseA.then(function(result) {
+ *   return promiseB;
+ * });
+ *
+ * deferredA.resolve('X');
+ * // promiseC not yet resolved
+ *
+ * deferredB.resolve('Y');
+ * // promiseC now resolved, with the value 'Y';
+ * </pre>
+ *  
+ * ## Deferring resolution of a promise
+ *  
+ * A promise's resolution can be deferred by resolving it with another promise. Using this
+ * technique, additional asynchronous functionality can be injected into chains.
+ *   
+ * <pre>
+ * var deferredA = $q.defer();
+ * var deferredB = $q.defer();
+ * var promiseA = deferredA.promise;
+ * var promiseB = deferredB.promise;
+ *
+ * deferredA.resolve(promiseB);
+ * // promiseA not yet resolved
+ *
+ * deferredB.resolve('X');
+ * // Both promiseB and promiseA are now resolved, in that order.
+ * // promiseA is resolved with the value 'X';
+ * </pre>
  *
  *
  * # Differences between Kris Kowal's Q and $q