Bug 1321744. Part 4 - fix comments.
MozReview-Commit-ID: HPIDi9tUHD3
--- a/xpcom/threads/MozPromise.h
+++ b/xpcom/threads/MozPromise.h
@@ -73,30 +73,34 @@ struct ReturnTypeIs {
*
* MozPromises attempt to mirror the spirit of JS Promises to the extent that
* is possible (and desirable) in C++. While the intent is that MozPromises
* feel familiar to programmers who are accustomed to their JS-implemented cousin,
* we don't shy away from imposing restrictions and adding features that make
* sense for the use cases we encounter.
*
* A MozPromise is ThreadSafe, and may be ->Then()ed on any thread. The Then()
- * call accepts resolve and reject callbacks, and returns a MozPromise::Request.
- * The Request object serves several purposes for the consumer.
- *
- * (1) It allows the caller to cancel the delivery of the resolve/reject value
- * if it has not already occurred, via Disconnect() (this must be done on
- * the target thread to avoid racing).
+ * call accepts resolve and reject callbacks, and returns a magic object which
+ * will be implicitly converted to a MozPromise::Request or a MozPromise object
+ * depending on how the return value is used. The magic object serves several
+ * purposes for the consumer.
*
- * (2) It provides access to a "Completion Promise", which is roughly analagous
- * to the Promise returned directly by ->then() calls on JS promises. If
- * the resolve/reject callback returns a new MozPromise, that promise is
- * chained to the completion promise, such that its resolve/reject value
- * will be forwarded along when it arrives. If the resolve/reject callback
- * returns void, the completion promise is resolved/rejected with the same
- * value that was passed to the callback.
+ * (1) When converting to a MozPromise::Request, it allows the caller to
+ * cancel the delivery of the resolve/reject value if it has not already
+ * occurred, via Disconnect() (this must be done on the target thread to
+ * avoid racing).
+ *
+ * (2) When converting to a MozPromise (which is called a completion promise),
+ * it allows promise chaining so ->Then() can be called again to attach
+ * more resolve and reject callbacks. If the resolve/reject callback
+ * returns a new MozPromise, that promise is chained to the completion
+ * promise, such that its resolve/reject value will be forwarded along
+ * when it arrives. If the resolve/reject callback returns void, the
+ * completion promise is resolved/rejected with the same value that was
+ * passed to the callback.
*
* The MozPromise APIs skirt traditional XPCOM convention by returning nsRefPtrs
* (rather than already_AddRefed) from various methods. This is done to allow elegant
* chaining of calls without cluttering up the code with intermediate variables, and
* without introducing separate API variants for callers that want a return value
* (from, say, ->Then()) from those that don't.
*
* When IsExclusive is true, the MozPromise does a release-mode assertion that