docs($q): improve documentation of promises that resolve with another promise

Kent C. Dodds · petebacondarwin · commit 4eb16ae4b7f3 · 2015-04-27T14:20:31.000+01:00
Adds short explanation of promise chaining and a link for further explanation. Closes #11708 Closes #11712
diff --git a/src/ng/q.js b/src/ng/q.js
@@ -140,9 +140,11 @@
  *   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`, `errorCallback`. It also notifies via the return value of the
- *   `notifyCallback` method. The promise cannot be resolved or rejected from the notifyCallback
- *   method.
+ *   `successCallback`, `errorCallback` (unless that value is a promise, in which case it is resolved
+ *   with the value which is resolved in that promise using
+ *   [promise chaining](http://www.html5rocks.com/en/tutorials/es6/promises/#toc-promises-queues)).
+ *   It also notifies via the return value of the `notifyCallback` method. The promise cannot be
+ *   resolved or rejected from the notifyCallback method.
  *
  * - `catch(errorCallback)` – shorthand for `promise.then(null, errorCallback)`
  *

Original file line number	Diff line number	Diff line change
`@@ -140,9 +140,11 @@`
`140`	`140`	`* provide a progress indication, before the promise is resolved or rejected.`
`141`	`141`	`*`
`142`	`142`	`* This method returns a new promise which is resolved or rejected via the return value of the`
`143`		- * `successCallback`, `errorCallback`. It also notifies via the return value of the
`144`		- * `notifyCallback` method. The promise cannot be resolved or rejected from the notifyCallback
`145`		`- * method.`
	`143`	+ * `successCallback`, `errorCallback` (unless that value is a promise, in which case it is resolved
	`144`	`+ * with the value which is resolved in that promise using`
	`145`	`+ * [promise chaining](http://www.html5rocks.com/en/tutorials/es6/promises/#toc-promises-queues)).`
	`146`	+ * It also notifies via the return value of the `notifyCallback` method. The promise cannot be
	`147`	`+ * resolved or rejected from the notifyCallback method.`
`146`	`148`	`*`
`147`	`149`	* - `catch(errorCallback)` – shorthand for `promise.then(null, errorCallback)`
`148`	`150`	`*`