Update waitForX docs

addon/-wait-for.js

@@ -147,6 +147,9 @@ export function waitForEvent(object, eventName) {
  * immediately with the observed property's current value, and multiple
  * times thereafter whenever the property changes, until you return
  * a truthy value from the callback, or the current task is canceled.
+ * You can also pass in a non-Function value in place of the callback,
+ * in which case the task will continue executing when the property's
+ * value becomes the value that you passed in.
  *
  * ```js
  * import { task, waitForProperty } from 'ember-concurrency';
@@ -157,18 +160,25 @@ export function waitForEvent(object, eventName) {
  *     console.log("Waiting for `foo` to become 5");
  *
  *     yield waitForProperty(this, 'foo', v => v === 5);
+ *     // alternatively: yield waitForProperty(this, 'foo', 5);
  *
  *     // somewhere else: this.set('foo', 5)
  *
  *     console.log("`foo` is 5!");
+ *
+ *     // wait for another task to be idle before running:
+ *     yield waitForProperty(this, 'otherTask.isIdle');
+ *     console.log("otherTask is idle!");
  *   })
  * });
  * ```
  *
  * @param {object} object an object (most likely an Ember Object)
  * @param {string} key the property name that is observed for changes
- * @param {function} callback the callback that should return when the task should continue
- *                   executing
+ * @param {function} callbackOrValue a Function that should return a truthy value
+ *                                   when the task should continue executing, or
+ *                                   a non-Function value that the watched property
+ *                                   needs to equal before the task will continue running
  */
 export function waitForProperty(object, key, predicateCallback) {
   return new WaitForPropertyYieldable(object, key, predicateCallback);

tests/dummy/app/components/events-example/component.js

@@ -58,11 +58,11 @@ export default Component.extend(Evented, {
 
   foo: task(function * () {
     yield timeout(500);
-    this.set('state', `${this.state} Foo.`);
   }),
 
   bar: task(function * () {
     yield waitForProperty(this, 'foo.isIdle');
+    this.set('state', `${this.state} Foo is idle.`);
     yield timeout(500);
     this.set('bazValue', 42);
     this.set('state', `${this.state} Bar.`);

tests/dummy/app/components/events-example/template.hbs

@@ -3,11 +3,26 @@
 <p>
   In addition to pausing the execution of a task until a yielded promise
   resolves, it's also possible to pause the execution of a task until
-  an event fires (e.g. an Ember.Evented event like <code>didInsertElement</code>,
-  or a `click` event from a DOM element or jQuery selection), or some other
-  condition has been met.
+  some other event or condition occurs by using the following helpers:
 </p>
 
+<ul>
+  <li>
+    <a href="/api/global.html#waitForEvent">waitForEvent</a>
+    Pause the task until an Ember/DOM/jQuery event fires.
+  </li>
+  <li>
+    <a href="/api/global.html#waitForProperty">waitForProperty</a>
+    Pause the task until a property on an Ember object becomes
+    some expected value.
+  </li>
+  <li>
+    <a href="/api/global.html#waitForQueue">waitForQueue</a>
+    Pause the task and resume execution within a specific
+    Ember Run Loop queue.
+  </li>
+</ul>
+
 <p>
   The patterns described below can be seen as alternatives to using observers
   and other patterns that are often prone to abuse; proper use of observers or
@@ -27,7 +42,8 @@
 <h3>Waiting for Ember & DOM / jQuery Events</h3>
 
 <p>
-  You can use <code>waitForEvent(object, eventName)</code> to pause your task until
+  You can use <code>
+  <a href="/api/global.html#waitForEvent">waitForEvent(object, eventName)</a></code> to pause your task until
   an Ember.Evented or DOM / jQuery Event fires.
   <code>object</code> must include Ember.Evented (or support <code>.one()</code>
   and <code>.off()</code>) or be a valid DOM EventTarget (or support
@@ -93,7 +109,9 @@
 <h3>Waiting for a condition / property</h3>
 
 <p>
-  You can use <code>waitForProperty(object, property, callback)</code>
+  You can use <code>
+    <a href="/api/global.html#waitForProperty">waitForProperty(object, property, callbackOrValue)</a>
+  </code>
   to pause your task until a property on an Ember Object becomes a certain value.
   This can be used in a variety of use cases, including coordination execution
   between concurrent tasks.
@@ -104,9 +122,9 @@
   Start
 </button>
 
-<h4>
+<h5>
   State: {{state}}
-</h4>
+</h5>
 {{!END-SNIPPET}}
 
 {{code-snippet name="waitForProperty.js"}}