From 976ed37dd79179644bf7a114e6ad5c7a945b0454 Mon Sep 17 00:00:00 2001
From: "Barnes, Dan" <dbarnes1@paychex.com>
Date: Tue, 22 Oct 2019 10:51:45 -0400
Subject: [PATCH] docs: improve examples

---
 README.md                   |   6 +-
 docs/BloodhoundPromise.html | 206 ++++++++++++++++++++++++------------
 docs/global.html            |  20 ++--
 docs/index.html             |   8 +-
 docs/index.js.html          | 128 +++++++++++++---------
 docs/module-index.html      |   6 +-
 index.js                    | 113 ++++++++++++--------
 test/index.js               |  63 +++++++++++
 8 files changed, 368 insertions(+), 182 deletions(-)

diff --git a/README.md b/README.md
index 8b7afac..227af6c 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,7 @@ BloodhoundPromise.all([
 
 What does the code do? Both `loadMessages` and `loadAppData` return a promise that will resolve once their data calls complete. Because the promises are being returned, we do not call `done()` -- after all, we need these promises for our call to `BloodhoundPromise.all`, so we can't end the chain just yet.
 
-then, we wrap our promises in a call to `BloodhoundPromise.all`, a static method that returns a promise which is only resolved if all child promises resolve.
+Then, we wrap our promises in a call to `BloodhoundPromise.all`, a static method that returns a promise which is only resolved if all child promises resolve.
 
 Finally, we call `done()`, which waits until the promise is either resolved or rejected to check for unhandled exceptions. If one of our data calls failed, an error will be thrown at this point. Otherwise, the error might be swallowed.
 
@@ -136,8 +136,8 @@ BloodhoundPromise.config.setErrorHandler(function handler(reason) {
 Sometimes you want to know that an asynchronous operation has occurred so you can perform change detection. Frameworks like AngularJS need this information to ensure that bindings are updated correctly.
 
 ```javascript
-angular.module('myapp', [])
-    .run(['$rootScope', function($rootScope) {
+angular.module('myapp', ['ng'])
+    .run(['$rootScope', function checkForChanges($rootScope) {
         function checkChanges() {
             $rootScope.$applyAsync();
         }
diff --git a/docs/BloodhoundPromise.html b/docs/BloodhoundPromise.html
index 16a4fc2..b1a54c8 100644
--- a/docs/BloodhoundPromise.html
+++ b/docs/BloodhoundPromise.html
@@ -73,7 +73,7 @@ <h4 class="name" id="BloodhoundPromise"><span class="type-signature"></span>new
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line278">line 278</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line281">line 281</a>
     </li></ul></dd>
     
 
@@ -231,7 +231,7 @@ <h4 class="name" id=".config"><span class="type-signature">(static) </span>confi
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line714">line 714</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line737">line 737</a>
     </li></ul></dd>
     
 
@@ -321,7 +321,7 @@ <h4 class="name" id=".all"><span class="type-signature">(static) </span>all<span
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line649">line 649</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line659">line 659</a>
     </li></ul></dd>
     
 
@@ -376,7 +376,9 @@ <h5>Examples</h5>
     
     <pre class="prettyprint"><code>BloodhoundPromise.all({
  a: someAsyncOperation(),
  b: BloodhoundPromise.delay(1000, 'default'),
  c: BloodhoundPromise.reject(new Error('oops'))
}).catch(console.log); // &lt;Error: oops></code></pre>
 
-    <pre class="prettyprint"><code>BloodhoundPromise.all([
  someAsyncOperation(),
  BloodhoundPromise.delay(1000, 'default')
]).then(console.log); // [ ..., 'default' ]</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.all([
  someAsyncOperation(),
  BloodhoundPromise.delay(1000, 'default')
]).then(console.log); // [ …, 'default' ]</code></pre>
+
+    <pre class="prettyprint"><code>BloodhoundPromise.all([
  'abc',
  new Error(123)
]).catch(console.error); // &lt;Error: 123></code></pre>
 
 
 
@@ -457,7 +459,8 @@ <h5>Returns:</h5>
     <p>A new promise resolved with an array of
 resolved values if an iterable was provided or an object if an object or Map was
 provided. The object's keys will be the keys in the original object and the values
-will be the resolved values.</p>
+will be the resolved values. If <em>any</em> of the promises rejects, the rejection handler
+will be invoked with the first rejection reason.</p>
 </div>
 
 
@@ -495,7 +498,7 @@ <h4 class="name" id=".any"><span class="type-signature">(static) </span>any<span
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line674">line 674</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line690">line 690</a>
     </li></ul></dd>
     
 
@@ -552,6 +555,8 @@ <h5>Examples</h5>
 
     <pre class="prettyprint"><code>BloodhoundPromise.any([
  someAsyncOperation(),
  BloodhoundPromise.delay(1000, 'default'),
  BloodhoundPromise.reject(new Error())
]).then(console.log); // [ 'default' ]</code></pre>
 
+    <pre class="prettyprint"><code>BloodhoundPromise.any([
  new Error(123),
  BloodhoundPromise.reject('abc')
]).catch(console.error); // [&lt;Error: 123>, 'abc']</code></pre>
+
 
 
 
@@ -630,8 +635,10 @@ <h5>Returns:</h5>
 <div class="param-desc">
     <p>A new promise resolved with an array containing
 the first resolved value if an iterable was provided or an object if an object or
-Map was provided. The object's 1 key will be the key of the first resolved promise in
-the original object and the value will be that first resolved value.</p>
+Map was provided. The object's only key will be the key of the first resolved promise in
+the original object and the value will be that first resolved value. If <em>all</em> of the
+promises reject, the rejection handler will be invoked with an array of all the rejection
+reasons.</p>
 </div>
 
 
@@ -669,7 +676,7 @@ <h4 class="name" id=".apply"><span class="type-signature">(static) </span>apply<
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line399">line 399</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line406">line 406</a>
     </li></ul></dd>
     
 
@@ -723,7 +730,7 @@ <h4 class="name" id=".apply"><span class="type-signature">(static) </span>apply<
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>function divide(arg1, arg2) {
  return arg1 / arg2;
}
BloodhoundPromise.apply(divide, [50, 10]).then(...);
BloodhoundPromise.apply(divide, [50, 0]).catch(...); // division by zero</code></pre>
+    <pre class="prettyprint"><code>function divide(arg1, arg2) {
  return arg1 / arg2;
}
BloodhoundPromise.apply(divide, [50, 10]).then(…);
BloodhoundPromise.apply(divide, [50, 0]).catch(…); // division by zero</code></pre>
 
 
 
@@ -856,7 +863,7 @@ <h4 class="name" id=".call"><span class="type-signature">(static) </span>call<sp
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line421">line 421</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line428">line 428</a>
     </li></ul></dd>
     
 
@@ -910,7 +917,7 @@ <h4 class="name" id=".call"><span class="type-signature">(static) </span>call<sp
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>function divide(arg1, arg2) {
  return arg1 / arg2;
}
BloodhoundPromise.call(divide, 50, 10).then(...);
BloodhoundPromise.call(divide, 50, 0).catch(...); // division by zero</code></pre>
+    <pre class="prettyprint"><code>function divide(arg1, arg2) {
  return arg1 / arg2;
}
BloodhoundPromise.call(divide, 50, 10).then(…);
BloodhoundPromise.call(divide, 50, 0).catch(…); // division by zero</code></pre>
 
 
 
@@ -1063,7 +1070,7 @@ <h4 class="name" id=".cast"><span class="type-signature">(static) </span>cast<sp
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line447">line 447</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line454">line 454</a>
     </li></ul></dd>
     
 
@@ -1116,7 +1123,7 @@ <h4 class="name" id=".cast"><span class="type-signature">(static) </span>cast<sp
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.cast(123).then(...);
BloodhoundPromise.cast(anotherPromise).then(..., ...);</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.cast(123).then(…);
BloodhoundPromise.cast(anotherPromise).then(…, …);</code></pre>
 
 
 
@@ -1229,7 +1236,7 @@ <h4 class="name" id=".defer"><span class="type-signature">(static) </span>defer<
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line356">line 356</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line360">line 360</a>
     </li></ul></dd>
     
 
@@ -1248,6 +1255,8 @@ <h4 class="name" id=".defer"><span class="type-signature">(static) </span>defer<
     
 
     
+        <dt class="important tag-deprecated">Deprecated:</dt><dd><ul class="dummy"><li>The Defer pattern breaks encapsulation and divides responsibility, and so
should be avoided. Instead, use the normal Promise constructor callback pattern.</li></ul></dd>
+    
 
     
 
@@ -1283,7 +1292,7 @@ <h4 class="name" id=".defer"><span class="type-signature">(static) </span>defer<
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>const defer = BloodhoundPromise.defer();
setTimeout(() => defer.resolve(123));
defer.promise.then(...);</code></pre>
+    <pre class="prettyprint"><code>// WARNING: deprecated
const defer = BloodhoundPromise.defer();
setTimeout(() => defer.resolve('abc'), 10);
defer.promise.then(…);</code></pre>
 
 
 
@@ -1344,7 +1353,7 @@ <h4 class="name" id=".delay"><span class="type-signature">(static) </span>delay<
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line498">line 498</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line505">line 505</a>
     </li></ul></dd>
     
 
@@ -1399,7 +1408,7 @@ <h4 class="name" id=".delay"><span class="type-signature">(static) </span>delay<
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.delay(1000, 'async value').then(...);
BloodhoundPromise.delay(1000, new Error('rejected')).catch(...);</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.delay(1000, 'async value').then(…);
BloodhoundPromise.delay(1000, new Error('rejected')).catch(…);</code></pre>
 
 
 
@@ -1532,7 +1541,7 @@ <h4 class="name" id=".isPromise"><span class="type-signature">(static) </span>is
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line466">line 466</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line473">line 473</a>
     </li></ul></dd>
     
 
@@ -1695,7 +1704,7 @@ <h4 class="name" id=".race"><span class="type-signature">(static) </span>race<sp
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line484">line 484</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line491">line 491</a>
     </li></ul></dd>
     
 
@@ -1748,7 +1757,7 @@ <h4 class="name" id=".race"><span class="type-signature">(static) </span>race<sp
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.race([
    someAsyncOperation(),
    BloodhoundPromise.delay(10000, new Error('operation timed out'))
]).then(..., ...);</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.race([
    someAsyncOperation(),
    BloodhoundPromise.delay(10000, new Error('operation timed out'))
]).then(…, …);</code></pre>
 
 
 
@@ -1858,7 +1867,7 @@ <h4 class="name" id=".reject"><span class="type-signature">(static) </span>rejec
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line343">line 343</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line346">line 346</a>
     </li></ul></dd>
     
 
@@ -1898,7 +1907,8 @@ <h4 class="name" id=".reject"><span class="type-signature">(static) </span>rejec
 
 
 <div class="description">
-    <p>Creates a new BloodhoundPromise rejected with the given reason.</p>
+    <p>Creates a new BloodhoundPromise rejected with the given reason. Best practice is to
+always reject your Promises with an Error instance, not a string or <code>undefined</code>.</p>
 </div>
 
 
@@ -2021,7 +2031,7 @@ <h4 class="name" id=".resolve"><span class="type-signature">(static) </span>reso
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line327">line 327</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line330">line 330</a>
     </li></ul></dd>
     
 
@@ -2075,7 +2085,7 @@ <h4 class="name" id=".resolve"><span class="type-signature">(static) </span>reso
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.resolve(123);
BloodhoundPromise.resolve(someOtherPromise).then(...);
BloodhoundPromise.resolve(new Error('rejection reason')).catch(...);</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.resolve(123);
BloodhoundPromise.resolve(someOtherPromise).then(…);
BloodhoundPromise.resolve(new Error('rejection reason')).catch(…);</code></pre>
 
 
 
@@ -2185,7 +2195,7 @@ <h4 class="name" id=".settle"><span class="type-signature">(static) </span>settl
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line517">line 517</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line524">line 524</a>
     </li></ul></dd>
     
 
@@ -2225,8 +2235,8 @@ <h4 class="name" id=".settle"><span class="type-signature">(static) </span>settl
 
 
 <div class="description">
-    <p>Resolves the returned promise when all the given promises either
-resolve or reject.</p>
+    <p>Resolves the returned promise when all the given promises settle
+(resolved <em>or</em> rejected).</p>
 </div>
 
 
@@ -2322,7 +2332,10 @@ <h5>Returns:</h5>
     <p>A new promise instance resolved
 with an array of promises if an iterable was provided.or an object if an
 object or Map was provided. The object's keys will be the keys in
-the original object; the values will be the promises.</p>
+the original object and the values will be the promises. To determine the
+state of the Promise instance use <a href="BloodhoundPromise.html#isResolved">isResolved()</a>
+or <a href="BloodhoundPromise.html#isRejected">isRejected()</a>. To get the rejection
+reason or resolved value, use <a href="BloodhoundPromise.html#value">value()</a>.</p>
 </div>
 
 
@@ -2360,7 +2373,7 @@ <h4 class="name" id=".some"><span class="type-signature">(static) </span>some<sp
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line575">line 575</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line585">line 585</a>
     </li></ul></dd>
     
 
@@ -2416,9 +2429,9 @@ <h4 class="name" id=".some"><span class="type-signature">(static) </span>some<sp
 
     <h5>Examples</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.some({
  a: someAsyncOperation(),
  b: BloodhoundPromise.delay(1000, 'default'),
  c: BloodhoundPromise.reject(new Error())
}, 2).then(console.log); // { a: ..., b: 'default' }</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.some({
  a: someAsyncOperation(),
  b: BloodhoundPromise.delay(1000, 'default'),
  c: BloodhoundPromise.reject(new Error())
}, 2).then(console.log); // { a: …, b: 'default' }</code></pre>
 
-    <pre class="prettyprint"><code>BloodhoundPromise.some([
  someAsyncOperation(),
  BloodhoundPromise.delay(1000, 'default'),
  BloodhoundPromise.reject(new Error())
], 2).then(console.log); // [ ..., 'default' ]</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.some([
  someAsyncOperation(),
  BloodhoundPromise.delay(1000, 'default'),
  BloodhoundPromise.reject(new Error())
], 2).then(console.log); // [ …, 'default' ]</code></pre>
 
 
 
@@ -2561,7 +2574,7 @@ <h4 class="name" id=".timeout"><span class="type-signature">(static) </span>time
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line377">line 377</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line384">line 384</a>
     </li></ul></dd>
     
 
@@ -2617,7 +2630,7 @@ <h4 class="name" id=".timeout"><span class="type-signature">(static) </span>time
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.timeout(somePromise, 10000).catch(...);
BloodhoundPromise.timeout(somePromise, 500, new Error('operation timed out'));</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.timeout(somePromise, 10000).catch(…);
BloodhoundPromise.timeout(somePromise, 500, new Error('operation timed out'));</code></pre>
 
 
 
@@ -2801,7 +2814,7 @@ <h4 class="name" id=".unwrap"><span class="type-signature">(static) </span>unwra
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line700">line 700</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line723">line 723</a>
     </li></ul></dd>
     
 
@@ -2855,7 +2868,7 @@ <h4 class="name" id=".unwrap"><span class="type-signature">(static) </span>unwra
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>const Promise = BloodhoundPromise.unwrap();
return new Promise((resolve, reject) => { ... });</code></pre>
+    <pre class="prettyprint"><code>const Promise = BloodhoundPromise.unwrap();
return new Promise((resolve, reject) => { … });</code></pre>
 
 
 
@@ -2904,7 +2917,7 @@ <h5>Returns:</h5>
 
     
 
-    <h4 class="name" id="catch"><span class="type-signature"></span>catch<span class="signature">(&hellip;types<span class="signature-attributes">opt</span>, onRejected)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
+    <h4 class="name" id="catch"><span class="type-signature"></span>catch<span class="signature">(&hellip;types<span class="signature-attributes">opt</span>, onRejected<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
 
     
 
@@ -2916,7 +2929,7 @@ <h4 class="name" id="catch"><span class="type-signature"></span>catch<span class
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line901">line 901</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line927">line 927</a>
     </li></ul></dd>
     
 
@@ -3056,6 +3069,8 @@ <h5>Parameters:</h5>
             
                 <td class="attributes">
                 
+                    &lt;optional><br>
+                
 
                 
 
@@ -3131,7 +3146,7 @@ <h4 class="name" id="done"><span class="type-signature"></span>done<span class="
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line809">line 809</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line835">line 835</a>
     </li></ul></dd>
     
 
@@ -3188,7 +3203,7 @@ <h5>Examples</h5>
     
     <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod)
  .tap(logResult)
  .then(handleResult)
  .catch() // swallow
  .done();</code></pre>
 
-    <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod)
  .then(handleResult)
  .done((valueOrError) => { ... });</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod)
  .then(handleResult)
  .done((valueOrError) => { … });</code></pre>
 
 
 
@@ -3278,7 +3293,7 @@ <h5>Parameters:</h5>
 
     
 
-    <h4 class="name" id="finally"><span class="type-signature"></span>finally<span class="signature">(callback)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
+    <h4 class="name" id="finally"><span class="type-signature"></span>finally<span class="signature">(callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
 
     
 
@@ -3290,7 +3305,7 @@ <h4 class="name" id="finally"><span class="type-signature"></span>finally<span c
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line987">line 987</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line1013">line 1013</a>
     </li></ul></dd>
     
 
@@ -3345,7 +3360,7 @@ <h4 class="name" id="finally"><span class="type-signature"></span>finally<span c
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>ui.showLoading(true);
BloodhoundPromise.call(someMethod)
  .then(...)
  .finally(() => ui.showLoading(false));</code></pre>
+    <pre class="prettyprint"><code>ui.showLoading(true);
BloodhoundPromise.call(someMethod)
  .then(…)
  .finally(() => ui.showLoading(false));</code></pre>
 
 
 
@@ -3363,6 +3378,8 @@ <h5>Parameters:</h5>
         <th>Type</th>
 
         
+        <th>Attributes</th>
+        
 
         
 
@@ -3388,6 +3405,16 @@ <h5>Parameters:</h5>
             </td>
 
             
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
 
             
 
@@ -3456,7 +3483,7 @@ <h4 class="name" id="isRejected"><span class="type-signature"></span>isRejected<
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line770">line 770</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line796">line 796</a>
     </li></ul></dd>
     
 
@@ -3570,7 +3597,7 @@ <h4 class="name" id="isResolved"><span class="type-signature"></span>isResolved<
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line756">line 756</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line782">line 782</a>
     </li></ul></dd>
     
 
@@ -3684,7 +3711,7 @@ <h4 class="name" id="isSettled"><span class="type-signature"></span>isSettled<sp
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line784">line 784</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line810">line 810</a>
     </li></ul></dd>
     
 
@@ -3798,7 +3825,7 @@ <h4 class="name" id="notify"><span class="type-signature"></span>notify<span cla
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line798">line 798</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line824">line 824</a>
     </li></ul></dd>
     
 
@@ -3897,7 +3924,7 @@ <h5>Returns:</h5>
 
     
 
-    <h4 class="name" id="spread"><span class="type-signature"></span>spread<span class="signature">(callback)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
+    <h4 class="name" id="spread"><span class="type-signature"></span>spread<span class="signature">(callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
 
     
 
@@ -3909,7 +3936,7 @@ <h4 class="name" id="spread"><span class="type-signature"></span>spread<span cla
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line961">line 961</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line987">line 987</a>
     </li></ul></dd>
     
 
@@ -3964,7 +3991,7 @@ <h4 class="name" id="spread"><span class="type-signature"></span>spread<span cla
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.all([
  'value for arg 1',
  BloodhoundPromise.call(getValueForArg2),
  BloodhoundPromise.resolve(getValueForArg3()),
]).spread((arg1, arg2, arg3) => { ... });</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.all([
  'value for arg 1',
  BloodhoundPromise.call(getValueForArg2),
  BloodhoundPromise.resolve(getValueForArg3()),
]).spread((arg1, arg2, arg3) => { … });</code></pre>
 
 
 
@@ -3982,6 +4009,8 @@ <h5>Parameters:</h5>
         <th>Type</th>
 
         
+        <th>Attributes</th>
+        
 
         
 
@@ -4007,6 +4036,16 @@ <h5>Parameters:</h5>
             </td>
 
             
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
 
             
 
@@ -4063,7 +4102,7 @@ <h5>Returns:</h5>
 
     
 
-    <h4 class="name" id="tap"><span class="type-signature"></span>tap<span class="signature">(callback)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
+    <h4 class="name" id="tap"><span class="type-signature"></span>tap<span class="signature">(callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
 
     
 
@@ -4075,7 +4114,7 @@ <h4 class="name" id="tap"><span class="type-signature"></span>tap<span class="si
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line933">line 933</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line959">line 959</a>
     </li></ul></dd>
     
 
@@ -4115,10 +4154,10 @@ <h4 class="name" id="tap"><span class="type-signature"></span>tap<span class="si
 
 
 <div class="description">
-    <p>Invokes the specified callback only if the promise resolves. If the
-callback returns a promise, the promise chain will wait for that promise
-to settle, but neither a fulfillment nor a rejection will be propagated
-to the next promise in the chain. Instead, the original resolved value
+    <p>Used for side effects. Invokes the specified callback only if the promise
+resolves. If the callback returns a promise, the promise chain will wait
+for that promise to settle but <strong>will not</strong> propagate the settled value
+to the next promise in the chain. Instead, the <em>original</em> resolved value
 will always be propagated.</p>
 </div>
 
@@ -4132,7 +4171,7 @@ <h4 class="name" id="tap"><span class="type-signature"></span>tap<span class="si
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod, 'arg')
  .tap(result => log.info('method succeeded', result))
  .then(result => { ... });</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod, 'arg')
  .tap(result => log.info('method succeeded', result))
  .then(result => { … });</code></pre>
 
 
 
@@ -4150,6 +4189,8 @@ <h5>Parameters:</h5>
         <th>Type</th>
 
         
+        <th>Attributes</th>
+        
 
         
 
@@ -4175,6 +4216,16 @@ <h5>Parameters:</h5>
             </td>
 
             
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
 
             
 
@@ -4233,7 +4284,7 @@ <h5>Returns:</h5>
 
     
 
-    <h4 class="name" id="then"><span class="type-signature"></span>then<span class="signature">(onFulfilled, onRejected)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
+    <h4 class="name" id="then"><span class="type-signature"></span>then<span class="signature">(onFulfilled<span class="signature-attributes">opt</span>, onRejected<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {<a href="BloodhoundPromise.html">BloodhoundPromise</a>}</span></h4>
 
     
 
@@ -4245,7 +4296,7 @@ <h4 class="name" id="then"><span class="type-signature"></span>then<span class="
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line858">line 858</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line884">line 884</a>
     </li></ul></dd>
     
 
@@ -4318,6 +4369,8 @@ <h5>Parameters:</h5>
         <th>Type</th>
 
         
+        <th>Attributes</th>
+        
 
         
 
@@ -4343,6 +4396,16 @@ <h5>Parameters:</h5>
             </td>
 
             
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
 
             
 
@@ -4367,6 +4430,16 @@ <h5>Parameters:</h5>
             </td>
 
             
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
 
             
 
@@ -4435,7 +4508,7 @@ <h4 class="name" id="timeout"><span class="type-signature"></span>timeout<span c
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line836">line 836</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line862">line 862</a>
     </li></ul></dd>
     
 
@@ -4491,7 +4564,7 @@ <h4 class="name" id="timeout"><span class="type-signature"></span>timeout<span c
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod, 'arg')
  .timeout(10000, new Error('operation timed out'))
  .then(...);
  .catch(...);</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.call(someMethod, 'arg')
  .timeout(10000, new Error('operation timed out'))
  .then(…);
  .catch(…);</code></pre>
 
 
 
@@ -4646,7 +4719,7 @@ <h4 class="name" id="unwrap"><span class="type-signature"></span>unwrap<span cla
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line1014">line 1014</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line1040">line 1040</a>
     </li></ul></dd>
     
 
@@ -4762,7 +4835,7 @@ <h4 class="name" id="value"><span class="type-signature"></span>value<span class
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line742">line 742</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line765">line 765</a>
     </li></ul></dd>
     
 
@@ -4815,7 +4888,7 @@ <h4 class="name" id="value"><span class="type-signature"></span>value<span class
 
     <h5>Example</h5>
     
-    <pre class="prettyprint"><code>BloodhoundPromise.resolve(123).value(); // 123</code></pre>
+    <pre class="prettyprint"><code>BloodhoundPromise.resolve(123).value(); // 123
BloodhoundPromise.delay(10, 123).value(); // undefined (not yet settled)
BloodhoundPromise.reject(new Error('oops')).value(); // &lt;Error: oops></code></pre>
 
 
 
@@ -4838,7 +4911,8 @@ <h5>Returns:</h5>
 
         
 <div class="param-desc">
-    <p>The resolved value or rejection reason.</p>
+    <p>The resolved value or rejection reason. If the Promise has
+not been settled, returns <code>undefined</code>.</p>
 </div>
 
 
@@ -4879,7 +4953,7 @@ <h5>Returns:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Wed Sep 04 2019 14:45:45 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Oct 22 2019 10:46:02 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>
diff --git a/docs/global.html b/docs/global.html
index e712705..7287a8d 100644
--- a/docs/global.html
+++ b/docs/global.html
@@ -140,7 +140,7 @@ <h4 class="name" id="AsyncNotifier"><span class="type-signature"></span>AsyncNot
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line57">line 57</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line58">line 58</a>
     </li></ul></dd>
     
 
@@ -223,7 +223,7 @@ <h4 class="name" id="Config">Config</h4>
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line74">line 74</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line75">line 75</a>
     </li></ul></dd>
     
 
@@ -304,7 +304,7 @@ <h5 class="subsection-title">Properties:</h5>
 
             <td class="description last"><p>Registers a callback to invoke when the
 wrapped Promise's scheduler is used (e.g. when invoking success and failure handlers
-passed to <code>.then(...)</code>).</p></td>
+passed to <code>.then(…)</code>).</p></td>
         </tr>
 
     
@@ -375,7 +375,7 @@ <h4 class="name" id="Defer">Defer</h4>
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line27">line 27</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line28">line 28</a>
     </li></ul></dd>
     
 
@@ -574,7 +574,7 @@ <h4 class="name" id="ErrorHandler"><span class="type-signature"></span>ErrorHand
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line39">line 39</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line40">line 40</a>
     </li></ul></dd>
     
 
@@ -710,7 +710,7 @@ <h4 class="name" id="Executor"><span class="type-signature"></span>Executor<span
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line17">line 17</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line18">line 18</a>
     </li></ul></dd>
     
 
@@ -870,7 +870,7 @@ <h4 class="name" id="SetAsyncNotifier"><span class="type-signature"></span>SetAs
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line64">line 64</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line65">line 65</a>
     </li></ul></dd>
     
 
@@ -912,7 +912,7 @@ <h4 class="name" id="SetAsyncNotifier"><span class="type-signature"></span>SetAs
 <div class="description">
     <p>Registers a callback to invoke when the
 wrapped Promise's scheduler is used (e.g. when invoking success and failure handlers
-passed to <code>.then(...)</code>).</p>
+passed to <code>.then(…)</code>).</p>
 </div>
 
 
@@ -1008,7 +1008,7 @@ <h4 class="name" id="SetErrorHandler"><span class="type-signature"></span>SetErr
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line47">line 47</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line48">line 48</a>
     </li></ul></dd>
     
 
@@ -1147,7 +1147,7 @@ <h5>Parameters:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Wed Sep 04 2019 14:45:45 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Oct 22 2019 10:46:02 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>
diff --git a/docs/index.html b/docs/index.html
index 7f2bf88..3ce5c0e 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -134,7 +134,7 @@ <h3>Explicit Promise Chains</h3>
 ]).done();
 </code></pre>
 <p>What does the code do? Both <code>loadMessages</code> and <code>loadAppData</code> return a promise that will resolve once their data calls complete. Because the promises are being returned, we do not call <code>done()</code> -- after all, we need these promises for our call to <code>BloodhoundPromise.all</code>, so we can't end the chain just yet.</p>
-<p>then, we wrap our promises in a call to <code>BloodhoundPromise.all</code>, a static method that returns a promise which is only resolved if all child promises resolve.</p>
+<p>Then, we wrap our promises in a call to <code>BloodhoundPromise.all</code>, a static method that returns a promise which is only resolved if all child promises resolve.</p>
 <p>Finally, we call <code>done()</code>, which waits until the promise is either resolved or rejected to check for unhandled exceptions. If one of our data calls failed, an error will be thrown at this point. Otherwise, the error might be swallowed.</p>
 <h3>Easy Configuration</h3>
 <p>Bloodhound is configurable.</p>
@@ -146,8 +146,8 @@ <h4>custom handler for any unhandled rejections</h4>
 </code></pre>
 <h4>callback for asynchronous operations</h4>
 <p>Sometimes you want to know that an asynchronous operation has occurred so you can perform change detection. Frameworks like AngularJS need this information to ensure that bindings are updated correctly.</p>
-<pre class="prettyprint source lang-javascript"><code>angular.module('myapp', [])
-    .run(['$rootScope', function($rootScope) {
+<pre class="prettyprint source lang-javascript"><code>angular.module('myapp', ['ng'])
+    .run(['$rootScope', function checkForChanges($rootScope) {
         function checkChanges() {
             $rootScope.$applyAsync();
         }
@@ -185,7 +185,7 @@ <h2>Copyright</h2>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Wed Sep 04 2019 14:45:45 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Oct 22 2019 10:46:02 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>
diff --git a/docs/index.js.html b/docs/index.js.html
index 92430b2..a72077c 100644
--- a/docs/index.js.html
+++ b/docs/index.js.html
@@ -47,6 +47,7 @@ <h1 class="page-title">index.js</h1>
             <pre class="prettyprint source linenums"><code>import has from 'lodash/has';
 import noop from 'lodash/noop';
 import size from 'lodash/size';
+import invoke from 'lodash/invoke';
 import attempt from 'lodash/attempt';
 import constant from 'lodash/constant';
 import flatten from 'lodash/flatten';
@@ -110,7 +111,7 @@ <h1 class="page-title">index.js</h1>
 /**
  * Registers a callback to invoke when the
  * wrapped Promise's scheduler is used (e.g. when invoking success and failure handlers
- * passed to `.then(...)`).
+ * passed to `.then(…)`).
  *
  * @global
  * @callback SetAsyncNotifier
@@ -124,7 +125,7 @@ <h1 class="page-title">index.js</h1>
  * @typedef {Object} Config
  * @property {SetAsyncNotifier} setAsyncNotifier Registers a callback to invoke when the
  * wrapped Promise's scheduler is used (e.g. when invoking success and failure handlers
- * passed to `.then(...)`).
+ * passed to `.then(…)`).
  * @property {SetErrorHandler} setErrorHandler Registers a callback to invoke when `done()`
  * is called on a rejected promise chain. The handler will be invoked with the rejection
  * reason.
@@ -133,9 +134,9 @@ <h1 class="page-title">index.js</h1>
 const RESOLVED = 1;
 const REJECTED = 2;
 
-const STATE = 'Symbol' in global ? Symbol('STATE') : '_state';
-const VALUE = 'Symbol' in global ? Symbol('_value') : '_value';
-const SETTLED = 'Symbol' in global ? Symbol('SETTLED') : '_settled';
+const STATE = [invoke(global, 'Symbol', 'STATE'), '_state'].find(Boolean);
+const VALUE = [invoke(global, 'Symbol', '_value'), '_value'].find(Boolean);
+const SETTLED = [invoke(global, 'Symbol', 'SETTLED'), '_settled'].find(Boolean);
 
 const readonly = value => ({
     enumerable: false,
@@ -157,9 +158,11 @@ <h1 class="page-title">index.js</h1>
 }
 
 function isErrorOrTypeName(param) {
-    return isString(param) ||
+    return !!param &amp;&amp; (
+        isString(param) ||
         param === Error ||
-        isError(param.prototype);
+        isError(param.prototype)
+    );
 }
 
 function isInstanceOfTypeName(typename) {
@@ -250,7 +253,7 @@ <h1 class="page-title">index.js</h1>
  * - `Promise.call/fcall/try/attempt` created.
  * - `Promise.config.setErrorHandler` created.
  * - `Promise.config.setAsyncNotifier` created.
- * - Promise constructor callback will be invoked with a 3rd "notify" function...which does nothing.
+ * - Promise constructor callback will be invoked with a 3rd "notify" function…which does nothing.
  * - `Promise.defer.resolve` will reject the promise if an Error instance if provided.
  * - `Promise.some` will accept an array or object and resolve with the same type.
  * - `Promise.all` will accept an array or object and resolve with the same type.
@@ -379,15 +382,16 @@ <h1 class="page-title">index.js</h1>
      * @returns {BloodhoundPromise} A new promise instance resolved with the given value.
      * @example
      * BloodhoundPromise.resolve(123);
-     * BloodhoundPromise.resolve(someOtherPromise).then(...);
-     * BloodhoundPromise.resolve(new Error('rejection reason')).catch(...);
+     * BloodhoundPromise.resolve(someOtherPromise).then(…);
+     * BloodhoundPromise.resolve(new Error('rejection reason')).catch(…);
      */
     BloodhoundPromise.resolve = function resolve(value) {
         return new BloodhoundPromise((resolve) => resolve(value));
     };
 
     /**
-     * Creates a new BloodhoundPromise rejected with the given reason.
+     * Creates a new BloodhoundPromise rejected with the given reason. Best practice is to
+     * always reject your Promises with an Error instance, not a string or `undefined`.
      *
      * @function BloodhoundPromise.reject
      * @param {any} error The reason the promise is rejected.
@@ -405,10 +409,13 @@ <h1 class="page-title">index.js</h1>
      *
      * @function BloodhoundPromise.defer
      * @returns {Defer} A new Defer instance.
+     * @deprecated The Defer pattern breaks encapsulation and divides responsibility, and so
+     * should be avoided. Instead, use the normal Promise constructor callback pattern.
      * @example
+     * // WARNING: deprecated
      * const defer = BloodhoundPromise.defer();
-     * setTimeout(() => defer.resolve(123));
-     * defer.promise.then(...);
+     * setTimeout(() => defer.resolve('abc'), 10);
+     * defer.promise.then(…);
      */
     BloodhoundPromise.defer = function defer() {
         const result = {};
@@ -432,7 +439,7 @@ <h1 class="page-title">index.js</h1>
      * @param {any} [error] The optional value to reject the promise with if the time period elapsed before the given promise settles.
      * @returns {BloodhoundPromise} A new promise instance.
      * @example
-     * BloodhoundPromise.timeout(somePromise, 10000).catch(...);
+     * BloodhoundPromise.timeout(somePromise, 10000).catch(…);
      * BloodhoundPromise.timeout(somePromise, 500, new Error('operation timed out'));
      */
     BloodhoundPromise.timeout = function timeout(promise, ms, error) {
@@ -455,8 +462,8 @@ <h1 class="page-title">index.js</h1>
      * function divide(arg1, arg2) {
      *   return arg1 / arg2;
      * }
-     * BloodhoundPromise.apply(divide, [50, 10]).then(...);
-     * BloodhoundPromise.apply(divide, [50, 0]).catch(...); // division by zero
+     * BloodhoundPromise.apply(divide, [50, 10]).then(…);
+     * BloodhoundPromise.apply(divide, [50, 0]).catch(…); // division by zero
      */
     BloodhoundPromise.apply =
     BloodhoundPromise.fapply = function apply(fn, args) {
@@ -479,8 +486,8 @@ <h1 class="page-title">index.js</h1>
      * function divide(arg1, arg2) {
      *   return arg1 / arg2;
      * }
-     * BloodhoundPromise.call(divide, 50, 10).then(...);
-     * BloodhoundPromise.call(divide, 50, 0).catch(...); // division by zero
+     * BloodhoundPromise.call(divide, 50, 10).then(…);
+     * BloodhoundPromise.call(divide, 50, 0).catch(…); // division by zero
      */
     BloodhoundPromise.call =
     BloodhoundPromise.fcall =
@@ -501,8 +508,8 @@ <h1 class="page-title">index.js</h1>
      * the returned promise will be rejected with that reason.
      * @returns {BloodhoundPromise} A new promise instance.
      * @example
-     * BloodhoundPromise.cast(123).then(...);
-     * BloodhoundPromise.cast(anotherPromise).then(..., ...);
+     * BloodhoundPromise.cast(123).then(…);
+     * BloodhoundPromise.cast(anotherPromise).then(…, …);
      */
     BloodhoundPromise.cast =
     BloodhoundPromise.when = function cast(value) {
@@ -537,7 +544,7 @@ <h1 class="page-title">index.js</h1>
      * BloodhoundPromise.race([
      *     someAsyncOperation(),
      *     BloodhoundPromise.delay(10000, new Error('operation timed out'))
-     * ]).then(..., ...);
+     * ]).then(…, …);
      */
     BloodhoundPromise.race = Promise.race;
 
@@ -551,8 +558,8 @@ <h1 class="page-title">index.js</h1>
      * @param {any} result The value to settle the promise with.
      * @returns {BloodhoundPromise} A new promise instance.
      * @example
-     * BloodhoundPromise.delay(1000, 'async value').then(...);
-     * BloodhoundPromise.delay(1000, new Error('rejected')).catch(...);
+     * BloodhoundPromise.delay(1000, 'async value').then(…);
+     * BloodhoundPromise.delay(1000, new Error('rejected')).catch(…);
      */
     BloodhoundPromise.delay = function delay(ms, result) {
         const defer = BloodhoundPromise.defer();
@@ -561,8 +568,8 @@ <h1 class="page-title">index.js</h1>
     };
 
     /**
-     * Resolves the returned promise when all the given promises either
-     * resolve or reject.
+     * Resolves the returned promise when all the given promises settle
+     * (resolved _or_ rejected).
      *
      * @function BloodhoundPromise.settle
      * @alias BloodhoundPromise.hash
@@ -571,7 +578,10 @@ <h1 class="page-title">index.js</h1>
      * @returns {BloodhoundPromise&lt;array|object>} A new promise instance resolved
      * with an array of promises if an iterable was provided.or an object if an
      * object or Map was provided. The object's keys will be the keys in
-     * the original object; the values will be the promises.
+     * the original object and the values will be the promises. To determine the
+     * state of the Promise instance use {@link BloodhoundPromise#isResolved isResolved()}
+     * or {@link BloodhoundPromise#isRejected isRejected()}. To get the rejection
+     * reason or resolved value, use {@link BloodhoundPromise#value value()}.
      * @example
      * BloodhoundPromise.hash({
      *   a: someAsyncOperation(),
@@ -637,13 +647,13 @@ <h1 class="page-title">index.js</h1>
      *   a: someAsyncOperation(),
      *   b: BloodhoundPromise.delay(1000, 'default'),
      *   c: BloodhoundPromise.reject(new Error())
-     * }, 2).then(console.log); // { a: ..., b: 'default' }
+     * }, 2).then(console.log); // { a: …, b: 'default' }
      * @example
      * BloodhoundPromise.some([
      *   someAsyncOperation(),
      *   BloodhoundPromise.delay(1000, 'default'),
      *   BloodhoundPromise.reject(new Error())
-     * ], 2).then(console.log); // [ ..., 'default' ]
+     * ], 2).then(console.log); // [ …, 'default' ]
      */
     BloodhoundPromise.some = function some(promises, count) {
 
@@ -700,7 +710,8 @@ <h1 class="page-title">index.js</h1>
      * @returns {BloodhoundPromise&lt;array|object>} A new promise resolved with an array of
      * resolved values if an iterable was provided or an object if an object or Map was
      * provided. The object's keys will be the keys in the original object and the values
-     * will be the resolved values.
+     * will be the resolved values. If _any_ of the promises rejects, the rejection handler
+     * will be invoked with the first rejection reason.
      * @example
      * BloodhoundPromise.all({
      *   a: someAsyncOperation(),
@@ -711,7 +722,12 @@ <h1 class="page-title">index.js</h1>
      * BloodhoundPromise.all([
      *   someAsyncOperation(),
      *   BloodhoundPromise.delay(1000, 'default')
-     * ]).then(console.log); // [ ..., 'default' ]
+     * ]).then(console.log); // [ …, 'default' ]
+     * @example
+     * BloodhoundPromise.all([
+     *   'abc',
+     *   new Error(123)
+     * ]).catch(console.error); // &lt;Error: 123>
      */
     BloodhoundPromise.all = function all(promises) {
         return BloodhoundPromise.some(promises, size(promises));
@@ -724,8 +740,10 @@ <h1 class="page-title">index.js</h1>
      * @param {Iterable|Map|object} promises The promises to wait for one to resolve.
      * @returns {BloodhoundPromise&lt;array|object>} A new promise resolved with an array containing
      * the first resolved value if an iterable was provided or an object if an object or
-     * Map was provided. The object's 1 key will be the key of the first resolved promise in
-     * the original object and the value will be that first resolved value.
+     * Map was provided. The object's only key will be the key of the first resolved promise in
+     * the original object and the value will be that first resolved value. If _all_ of the
+     * promises reject, the rejection handler will be invoked with an array of all the rejection
+     * reasons.
      * @example
      * BloodhoundPromise.any({
      *   a: someAsyncOperation(),
@@ -738,6 +756,11 @@ <h1 class="page-title">index.js</h1>
      *   BloodhoundPromise.delay(1000, 'default'),
      *   BloodhoundPromise.reject(new Error())
      * ]).then(console.log); // [ 'default' ]
+     * @example
+     * BloodhoundPromise.any([
+     *   new Error(123),
+     *   BloodhoundPromise.reject('abc')
+     * ]).catch(console.error); // [&lt;Error: 123>, 'abc']
      */
     BloodhoundPromise.any = function any(promises) {
         return BloodhoundPromise.some(promises, 1);
@@ -751,7 +774,7 @@ <h1 class="page-title">index.js</h1>
      * @returns {function(new:Promise)} The original Promise constructor.
      * @example
      * const Promise = BloodhoundPromise.unwrap();
-     * return new Promise((resolve, reject) => { ... });
+     * return new Promise((resolve, reject) => { … });
      */
     BloodhoundPromise.unwrap = function unwrap() {
         return Promise;
@@ -790,9 +813,12 @@ <h1 class="page-title">index.js</h1>
      *
      * @function BloodhoundPromise.prototype.value
      * @alias BloodhoundPromise.prototype.getValue
-     * @returns {any} The resolved value or rejection reason.
+     * @returns {any} The resolved value or rejection reason. If the Promise has
+     * not been settled, returns `undefined`.
      * @example
      * BloodhoundPromise.resolve(123).value(); // 123
+     * BloodhoundPromise.delay(10, 123).value(); // undefined (not yet settled)
+     * BloodhoundPromise.reject(new Error('oops')).value(); // &lt;Error: oops>
      */
     BloodhoundPromise.prototype.value =
     BloodhoundPromise.prototype.getValue = function getValue() {
@@ -870,7 +896,7 @@ <h1 class="page-title">index.js</h1>
      * @example
      * BloodhoundPromise.call(someMethod)
      *   .then(handleResult)
-     *   .done((valueOrError) => { ... });
+     *   .done((valueOrError) => { … });
      */
     BloodhoundPromise.prototype.done = function done(callback) {
         this.then(callback, function unhandledRejection(error) {
@@ -894,8 +920,8 @@ <h1 class="page-title">index.js</h1>
      * @example
      * BloodhoundPromise.call(someMethod, 'arg')
      *   .timeout(10000, new Error('operation timed out'))
-     *   .then(...);
-     *   .catch(...);
+     *   .then(…);
+     *   .catch(…);
      */
     BloodhoundPromise.prototype.timeout = function timeout(ms, error) {
         return BloodhoundPromise.timeout(this, ms, error);
@@ -905,9 +931,9 @@ <h1 class="page-title">index.js</h1>
      * Invokes one of the specified callbacks when the promise settles.
      *
      * @function BloodhoundPromise.prototype.then
-     * @param {function} onFulfilled Method to invoke when the promise resolves.
+     * @param {function} [onFulfilled] Method to invoke when the promise resolves.
      * Will be passed the resolved value.
-     * @param {function} onRejected Method to invoke when the promise rejects.
+     * @param {function} [onRejected] Method to invoke when the promise rejects.
      * Will be passed the rejection reason.
      * @returns {BloodhoundPromise} A new promise.
      * @example
@@ -955,7 +981,7 @@ <h1 class="page-title">index.js</h1>
      * @param {...string[]} [types] The error type names to match against the
      * rejection reason in order for the callback to be invoked. If not provided,
      * the callback will always be invoked when the promise is rejected.
-     * @param {function} onRejected Method to invoke when the promise rejects. If
+     * @param {function} [onRejected] Method to invoke when the promise rejects. If
      * one or more Error type names has been specified, the callback will only be
      * invoked if the rejection reason matches the given Error type name.
      * @returns {BloodhoundPromise} A new promise.
@@ -977,14 +1003,14 @@ <h1 class="page-title">index.js</h1>
     };
 
     /**
-     * Invokes the specified callback only if the promise resolves. If the
-     * callback returns a promise, the promise chain will wait for that promise
-     * to settle, but neither a fulfillment nor a rejection will be propagated
-     * to the next promise in the chain. Instead, the original resolved value
+     * Used for side effects. Invokes the specified callback only if the promise
+     * resolves. If the callback returns a promise, the promise chain will wait
+     * for that promise to settle but **will not** propagate the settled value
+     * to the next promise in the chain. Instead, the _original_ resolved value
      * will always be propagated.
      *
      * @function BloodhoundPromise.prototype.tap
-     * @param {function} callback The method to invoke when the promise resolves.
+     * @param {function} [callback] The method to invoke when the promise resolves.
      * Will be passed the resolved value. Nothing this callback does will affect
      * the next promise in the chain, which will always be provided with the
      * original resolved value.
@@ -992,7 +1018,7 @@ <h1 class="page-title">index.js</h1>
      * @example
      * BloodhoundPromise.call(someMethod, 'arg')
      *   .tap(result => log.info('method succeeded', result))
-     *   .then(result => { ... });
+     *   .then(result => { … });
      */
     BloodhoundPromise.prototype.tap = function tap(callback) {
         return !isFunction(callback) ?
@@ -1010,7 +1036,7 @@ <h1 class="page-title">index.js</h1>
      * argument.
      *
      * @function BloodhoundPromise.prototype.spread
-     * @param {function} callback Method to invoke with the array of resolved
+     * @param {function} [callback] Method to invoke with the array of resolved
      * values passed in as arguments.
      * @returns {BloodhoundPromise} A new promise.
      * @example
@@ -1018,7 +1044,7 @@ <h1 class="page-title">index.js</h1>
      *   'value for arg 1',
      *   BloodhoundPromise.call(getValueForArg2),
      *   BloodhoundPromise.resolve(getValueForArg3()),
-     * ]).spread((arg1, arg2, arg3) => { ... });
+     * ]).spread((arg1, arg2, arg3) => { … });
      */
     BloodhoundPromise.prototype.spread = function spread(callback) {
         return !isFunction(callback) ?
@@ -1037,13 +1063,13 @@ <h1 class="page-title">index.js</h1>
      *
      * @function BloodhoundPromise.prototype.finally
      * @alias BloodhoundPromise.prototype.lastly
-     * @param {function} callback Method to invoke when the promise settles.
+     * @param {function} [callback] Method to invoke when the promise settles.
      * The method will be passed the resolved value or rejection reason.
      * @returns {BloodhoundPromise} A new promise.
      * @example
      * ui.showLoading(true);
      * BloodhoundPromise.call(someMethod)
-     *   .then(...)
+     *   .then(…)
      *   .finally(() => ui.showLoading(false));
      */
     BloodhoundPromise.prototype.lastly =
@@ -1093,7 +1119,7 @@ <h1 class="page-title">index.js</h1>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Wed Sep 04 2019 14:45:45 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Oct 22 2019 10:46:02 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>
diff --git a/docs/module-index.html b/docs/module-index.html
index 9b1e07e..d62a318 100644
--- a/docs/module-index.html
+++ b/docs/module-index.html
@@ -66,7 +66,7 @@ <h1 class="page-title">index</h1>
 <li><code>Promise.call/fcall/try/attempt</code> created.</li>
 <li><code>Promise.config.setErrorHandler</code> created.</li>
 <li><code>Promise.config.setAsyncNotifier</code> created.</li>
-<li>Promise constructor callback will be invoked with a 3rd &quot;notify&quot; function...which does nothing.</li>
+<li>Promise constructor callback will be invoked with a 3rd &quot;notify&quot; function…which does nothing.</li>
 <li><code>Promise.defer.resolve</code> will reject the promise if an Error instance if provided.</li>
 <li><code>Promise.some</code> will accept an array or object and resolve with the same type.</li>
 <li><code>Promise.all</code> will accept an array or object and resolve with the same type.</li>
@@ -111,7 +111,7 @@ <h1 class="page-title">index</h1>
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="index.js.html">index.js</a>, <a href="index.js.html#line263">line 263</a>
+        <a href="index.js.html">index.js</a>, <a href="index.js.html#line266">line 266</a>
     </li></ul></dd>
     
 
@@ -298,7 +298,7 @@ <h5>Returns:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Wed Sep 04 2019 14:45:45 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Tue Oct 22 2019 10:46:02 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>
diff --git a/index.js b/index.js
index 638b82f..43b0e9c 100644
--- a/index.js
+++ b/index.js
@@ -65,7 +65,7 @@ import toArray from 'lodash/toArray';
 /**
  * Registers a callback to invoke when the
  * wrapped Promise's scheduler is used (e.g. when invoking success and failure handlers
- * passed to `.then(...)`).
+ * passed to `.then(…)`).
  *
  * @global
  * @callback SetAsyncNotifier
@@ -79,7 +79,7 @@ import toArray from 'lodash/toArray';
  * @typedef {Object} Config
  * @property {SetAsyncNotifier} setAsyncNotifier Registers a callback to invoke when the
  * wrapped Promise's scheduler is used (e.g. when invoking success and failure handlers
- * passed to `.then(...)`).
+ * passed to `.then(…)`).
  * @property {SetErrorHandler} setErrorHandler Registers a callback to invoke when `done()`
  * is called on a rejected promise chain. The handler will be invoked with the rejection
  * reason.
@@ -207,7 +207,7 @@ function RESOLVER(promise, resolve, reject, x) {
  * - `Promise.call/fcall/try/attempt` created.
  * - `Promise.config.setErrorHandler` created.
  * - `Promise.config.setAsyncNotifier` created.
- * - Promise constructor callback will be invoked with a 3rd "notify" function...which does nothing.
+ * - Promise constructor callback will be invoked with a 3rd "notify" function…which does nothing.
  * - `Promise.defer.resolve` will reject the promise if an Error instance if provided.
  * - `Promise.some` will accept an array or object and resolve with the same type.
  * - `Promise.all` will accept an array or object and resolve with the same type.
@@ -336,15 +336,16 @@ function wrapAsBloodhound(Promise) {
      * @returns {BloodhoundPromise} A new promise instance resolved with the given value.
      * @example
      * BloodhoundPromise.resolve(123);
-     * BloodhoundPromise.resolve(someOtherPromise).then(...);
-     * BloodhoundPromise.resolve(new Error('rejection reason')).catch(...);
+     * BloodhoundPromise.resolve(someOtherPromise).then(…);
+     * BloodhoundPromise.resolve(new Error('rejection reason')).catch(…);
      */
     BloodhoundPromise.resolve = function resolve(value) {
         return new BloodhoundPromise((resolve) => resolve(value));
     };
 
     /**
-     * Creates a new BloodhoundPromise rejected with the given reason.
+     * Creates a new BloodhoundPromise rejected with the given reason. Best practice is to
+     * always reject your Promises with an Error instance, not a string or `undefined`.
      *
      * @function BloodhoundPromise.reject
      * @param {any} error The reason the promise is rejected.
@@ -362,10 +363,13 @@ function wrapAsBloodhound(Promise) {
      *
      * @function BloodhoundPromise.defer
      * @returns {Defer} A new Defer instance.
+     * @deprecated The Defer pattern breaks encapsulation and divides responsibility, and so
+     * should be avoided. Instead, use the normal Promise constructor callback pattern.
      * @example
+     * // WARNING: deprecated
      * const defer = BloodhoundPromise.defer();
-     * setTimeout(() => defer.resolve(123));
-     * defer.promise.then(...);
+     * setTimeout(() => defer.resolve('abc'), 10);
+     * defer.promise.then(…);
      */
     BloodhoundPromise.defer = function defer() {
         const result = {};
@@ -389,7 +393,7 @@ function wrapAsBloodhound(Promise) {
      * @param {any} [error] The optional value to reject the promise with if the time period elapsed before the given promise settles.
      * @returns {BloodhoundPromise} A new promise instance.
      * @example
-     * BloodhoundPromise.timeout(somePromise, 10000).catch(...);
+     * BloodhoundPromise.timeout(somePromise, 10000).catch(…);
      * BloodhoundPromise.timeout(somePromise, 500, new Error('operation timed out'));
      */
     BloodhoundPromise.timeout = function timeout(promise, ms, error) {
@@ -412,8 +416,8 @@ function wrapAsBloodhound(Promise) {
      * function divide(arg1, arg2) {
      *   return arg1 / arg2;
      * }
-     * BloodhoundPromise.apply(divide, [50, 10]).then(...);
-     * BloodhoundPromise.apply(divide, [50, 0]).catch(...); // division by zero
+     * BloodhoundPromise.apply(divide, [50, 10]).then(…);
+     * BloodhoundPromise.apply(divide, [50, 0]).catch(…); // division by zero
      */
     BloodhoundPromise.apply =
     BloodhoundPromise.fapply = function apply(fn, args) {
@@ -436,8 +440,8 @@ function wrapAsBloodhound(Promise) {
      * function divide(arg1, arg2) {
      *   return arg1 / arg2;
      * }
-     * BloodhoundPromise.call(divide, 50, 10).then(...);
-     * BloodhoundPromise.call(divide, 50, 0).catch(...); // division by zero
+     * BloodhoundPromise.call(divide, 50, 10).then(…);
+     * BloodhoundPromise.call(divide, 50, 0).catch(…); // division by zero
      */
     BloodhoundPromise.call =
     BloodhoundPromise.fcall =
@@ -458,8 +462,8 @@ function wrapAsBloodhound(Promise) {
      * the returned promise will be rejected with that reason.
      * @returns {BloodhoundPromise} A new promise instance.
      * @example
-     * BloodhoundPromise.cast(123).then(...);
-     * BloodhoundPromise.cast(anotherPromise).then(..., ...);
+     * BloodhoundPromise.cast(123).then(…);
+     * BloodhoundPromise.cast(anotherPromise).then(…, …);
      */
     BloodhoundPromise.cast =
     BloodhoundPromise.when = function cast(value) {
@@ -494,7 +498,7 @@ function wrapAsBloodhound(Promise) {
      * BloodhoundPromise.race([
      *     someAsyncOperation(),
      *     BloodhoundPromise.delay(10000, new Error('operation timed out'))
-     * ]).then(..., ...);
+     * ]).then(…, …);
      */
     BloodhoundPromise.race = Promise.race;
 
@@ -508,8 +512,8 @@ function wrapAsBloodhound(Promise) {
      * @param {any} result The value to settle the promise with.
      * @returns {BloodhoundPromise} A new promise instance.
      * @example
-     * BloodhoundPromise.delay(1000, 'async value').then(...);
-     * BloodhoundPromise.delay(1000, new Error('rejected')).catch(...);
+     * BloodhoundPromise.delay(1000, 'async value').then(…);
+     * BloodhoundPromise.delay(1000, new Error('rejected')).catch(…);
      */
     BloodhoundPromise.delay = function delay(ms, result) {
         const defer = BloodhoundPromise.defer();
@@ -518,8 +522,8 @@ function wrapAsBloodhound(Promise) {
     };
 
     /**
-     * Resolves the returned promise when all the given promises either
-     * resolve or reject.
+     * Resolves the returned promise when all the given promises settle
+     * (resolved _or_ rejected).
      *
      * @function BloodhoundPromise.settle
      * @alias BloodhoundPromise.hash
@@ -528,7 +532,10 @@ function wrapAsBloodhound(Promise) {
      * @returns {BloodhoundPromise<array|object>} A new promise instance resolved
      * with an array of promises if an iterable was provided.or an object if an
      * object or Map was provided. The object's keys will be the keys in
-     * the original object; the values will be the promises.
+     * the original object and the values will be the promises. To determine the
+     * state of the Promise instance use {@link BloodhoundPromise#isResolved isResolved()}
+     * or {@link BloodhoundPromise#isRejected isRejected()}. To get the rejection
+     * reason or resolved value, use {@link BloodhoundPromise#value value()}.
      * @example
      * BloodhoundPromise.hash({
      *   a: someAsyncOperation(),
@@ -594,13 +601,13 @@ function wrapAsBloodhound(Promise) {
      *   a: someAsyncOperation(),
      *   b: BloodhoundPromise.delay(1000, 'default'),
      *   c: BloodhoundPromise.reject(new Error())
-     * }, 2).then(console.log); // { a: ..., b: 'default' }
+     * }, 2).then(console.log); // { a: …, b: 'default' }
      * @example
      * BloodhoundPromise.some([
      *   someAsyncOperation(),
      *   BloodhoundPromise.delay(1000, 'default'),
      *   BloodhoundPromise.reject(new Error())
-     * ], 2).then(console.log); // [ ..., 'default' ]
+     * ], 2).then(console.log); // [ …, 'default' ]
      */
     BloodhoundPromise.some = function some(promises, count) {
 
@@ -657,7 +664,8 @@ function wrapAsBloodhound(Promise) {
      * @returns {BloodhoundPromise<array|object>} A new promise resolved with an array of
      * resolved values if an iterable was provided or an object if an object or Map was
      * provided. The object's keys will be the keys in the original object and the values
-     * will be the resolved values.
+     * will be the resolved values. If _any_ of the promises rejects, the rejection handler
+     * will be invoked with the first rejection reason.
      * @example
      * BloodhoundPromise.all({
      *   a: someAsyncOperation(),
@@ -668,7 +676,12 @@ function wrapAsBloodhound(Promise) {
      * BloodhoundPromise.all([
      *   someAsyncOperation(),
      *   BloodhoundPromise.delay(1000, 'default')
-     * ]).then(console.log); // [ ..., 'default' ]
+     * ]).then(console.log); // [ …, 'default' ]
+     * @example
+     * BloodhoundPromise.all([
+     *   'abc',
+     *   new Error(123)
+     * ]).catch(console.error); // <Error: 123>
      */
     BloodhoundPromise.all = function all(promises) {
         return BloodhoundPromise.some(promises, size(promises));
@@ -681,8 +694,10 @@ function wrapAsBloodhound(Promise) {
      * @param {Iterable|Map|object} promises The promises to wait for one to resolve.
      * @returns {BloodhoundPromise<array|object>} A new promise resolved with an array containing
      * the first resolved value if an iterable was provided or an object if an object or
-     * Map was provided. The object's 1 key will be the key of the first resolved promise in
-     * the original object and the value will be that first resolved value.
+     * Map was provided. The object's only key will be the key of the first resolved promise in
+     * the original object and the value will be that first resolved value. If _all_ of the
+     * promises reject, the rejection handler will be invoked with an array of all the rejection
+     * reasons.
      * @example
      * BloodhoundPromise.any({
      *   a: someAsyncOperation(),
@@ -695,6 +710,11 @@ function wrapAsBloodhound(Promise) {
      *   BloodhoundPromise.delay(1000, 'default'),
      *   BloodhoundPromise.reject(new Error())
      * ]).then(console.log); // [ 'default' ]
+     * @example
+     * BloodhoundPromise.any([
+     *   new Error(123),
+     *   BloodhoundPromise.reject('abc')
+     * ]).catch(console.error); // [<Error: 123>, 'abc']
      */
     BloodhoundPromise.any = function any(promises) {
         return BloodhoundPromise.some(promises, 1);
@@ -708,7 +728,7 @@ function wrapAsBloodhound(Promise) {
      * @returns {function(new:Promise)} The original Promise constructor.
      * @example
      * const Promise = BloodhoundPromise.unwrap();
-     * return new Promise((resolve, reject) => { ... });
+     * return new Promise((resolve, reject) => { … });
      */
     BloodhoundPromise.unwrap = function unwrap() {
         return Promise;
@@ -747,9 +767,12 @@ function wrapAsBloodhound(Promise) {
      *
      * @function BloodhoundPromise.prototype.value
      * @alias BloodhoundPromise.prototype.getValue
-     * @returns {any} The resolved value or rejection reason.
+     * @returns {any} The resolved value or rejection reason. If the Promise has
+     * not been settled, returns `undefined`.
      * @example
      * BloodhoundPromise.resolve(123).value(); // 123
+     * BloodhoundPromise.delay(10, 123).value(); // undefined (not yet settled)
+     * BloodhoundPromise.reject(new Error('oops')).value(); // <Error: oops>
      */
     BloodhoundPromise.prototype.value =
     BloodhoundPromise.prototype.getValue = function getValue() {
@@ -827,7 +850,7 @@ function wrapAsBloodhound(Promise) {
      * @example
      * BloodhoundPromise.call(someMethod)
      *   .then(handleResult)
-     *   .done((valueOrError) => { ... });
+     *   .done((valueOrError) => { … });
      */
     BloodhoundPromise.prototype.done = function done(callback) {
         this.then(callback, function unhandledRejection(error) {
@@ -851,8 +874,8 @@ function wrapAsBloodhound(Promise) {
      * @example
      * BloodhoundPromise.call(someMethod, 'arg')
      *   .timeout(10000, new Error('operation timed out'))
-     *   .then(...);
-     *   .catch(...);
+     *   .then(…);
+     *   .catch(…);
      */
     BloodhoundPromise.prototype.timeout = function timeout(ms, error) {
         return BloodhoundPromise.timeout(this, ms, error);
@@ -862,9 +885,9 @@ function wrapAsBloodhound(Promise) {
      * Invokes one of the specified callbacks when the promise settles.
      *
      * @function BloodhoundPromise.prototype.then
-     * @param {function} onFulfilled Method to invoke when the promise resolves.
+     * @param {function} [onFulfilled] Method to invoke when the promise resolves.
      * Will be passed the resolved value.
-     * @param {function} onRejected Method to invoke when the promise rejects.
+     * @param {function} [onRejected] Method to invoke when the promise rejects.
      * Will be passed the rejection reason.
      * @returns {BloodhoundPromise} A new promise.
      * @example
@@ -912,7 +935,7 @@ function wrapAsBloodhound(Promise) {
      * @param {...string[]} [types] The error type names to match against the
      * rejection reason in order for the callback to be invoked. If not provided,
      * the callback will always be invoked when the promise is rejected.
-     * @param {function} onRejected Method to invoke when the promise rejects. If
+     * @param {function} [onRejected] Method to invoke when the promise rejects. If
      * one or more Error type names has been specified, the callback will only be
      * invoked if the rejection reason matches the given Error type name.
      * @returns {BloodhoundPromise} A new promise.
@@ -934,14 +957,14 @@ function wrapAsBloodhound(Promise) {
     };
 
     /**
-     * Invokes the specified callback only if the promise resolves. If the
-     * callback returns a promise, the promise chain will wait for that promise
-     * to settle, but neither a fulfillment nor a rejection will be propagated
-     * to the next promise in the chain. Instead, the original resolved value
+     * Used for side effects. Invokes the specified callback only if the promise
+     * resolves. If the callback returns a promise, the promise chain will wait
+     * for that promise to settle but **will not** propagate the settled value
+     * to the next promise in the chain. Instead, the _original_ resolved value
      * will always be propagated.
      *
      * @function BloodhoundPromise.prototype.tap
-     * @param {function} callback The method to invoke when the promise resolves.
+     * @param {function} [callback] The method to invoke when the promise resolves.
      * Will be passed the resolved value. Nothing this callback does will affect
      * the next promise in the chain, which will always be provided with the
      * original resolved value.
@@ -949,7 +972,7 @@ function wrapAsBloodhound(Promise) {
      * @example
      * BloodhoundPromise.call(someMethod, 'arg')
      *   .tap(result => log.info('method succeeded', result))
-     *   .then(result => { ... });
+     *   .then(result => { … });
      */
     BloodhoundPromise.prototype.tap = function tap(callback) {
         return !isFunction(callback) ?
@@ -967,7 +990,7 @@ function wrapAsBloodhound(Promise) {
      * argument.
      *
      * @function BloodhoundPromise.prototype.spread
-     * @param {function} callback Method to invoke with the array of resolved
+     * @param {function} [callback] Method to invoke with the array of resolved
      * values passed in as arguments.
      * @returns {BloodhoundPromise} A new promise.
      * @example
@@ -975,7 +998,7 @@ function wrapAsBloodhound(Promise) {
      *   'value for arg 1',
      *   BloodhoundPromise.call(getValueForArg2),
      *   BloodhoundPromise.resolve(getValueForArg3()),
-     * ]).spread((arg1, arg2, arg3) => { ... });
+     * ]).spread((arg1, arg2, arg3) => { … });
      */
     BloodhoundPromise.prototype.spread = function spread(callback) {
         return !isFunction(callback) ?
@@ -994,13 +1017,13 @@ function wrapAsBloodhound(Promise) {
      *
      * @function BloodhoundPromise.prototype.finally
      * @alias BloodhoundPromise.prototype.lastly
-     * @param {function} callback Method to invoke when the promise settles.
+     * @param {function} [callback] Method to invoke when the promise settles.
      * The method will be passed the resolved value or rejection reason.
      * @returns {BloodhoundPromise} A new promise.
      * @example
      * ui.showLoading(true);
      * BloodhoundPromise.call(someMethod)
-     *   .then(...)
+     *   .then(…)
      *   .finally(() => ui.showLoading(false));
      */
     BloodhoundPromise.prototype.lastly =
diff --git a/test/index.js b/test/index.js
index a465f21..ca327dc 100644
--- a/test/index.js
+++ b/test/index.js
@@ -223,6 +223,9 @@ describe('Bloodhound', () => {
 
         describe('all', () => {
 
+            const err1 = new Error(1);
+            const err2 = new Error(2);
+
             it('calls some with length of array', done => {
                 const input = [1, 2, 3];
                 BloodhoundPromise.some = (object, count) => {
@@ -243,10 +246,42 @@ describe('Bloodhound', () => {
                 BloodhoundPromise.all(input);
             });
 
+            [
+                {
+                    type: 'array',
+                    arg: [
+                        err1,
+                        err2,
+                        'abc',
+                    ]
+                },
+                {
+                    type: 'object',
+                    arg: {
+                        a: err1,
+                        b: err2,
+                        c: 'abc',
+                    }
+                }
+            ].forEach(({ type, arg }) => {
+
+                it(`rejects with first reason if any ${type} promises reject`, done => {
+                    BloodhoundPromise.all(arg).catch(result => {
+                        expect(result).toEqual(err1);
+                        done();
+                    })
+                });
+
+            });
+
         });
 
         describe('any', () => {
 
+            const err1 = new Error(1);
+            const err2 = new Error(2);
+            const err3 = new Error(3);
+
             it('calls some with count 1', done => {
                 let callCount = 0;
                 BloodhoundPromise.some = (_, count) => {
@@ -258,6 +293,34 @@ describe('Bloodhound', () => {
                 BloodhoundPromise.any(object);
             });
 
+            [
+                {
+                    type: 'array',
+                    arg: [
+                        err1,
+                        err2,
+                        err3,
+                    ]
+                },
+                {
+                    type: 'object',
+                    arg: {
+                        a: err1,
+                        b: err2,
+                        c: err3,
+                    }
+                }
+            ].forEach(({ type, arg }) => {
+
+                it(`rejects with array of reasons if all ${type} promises reject`, done => {
+                    BloodhoundPromise.any(arg).catch(result => {
+                        expect(result).toEqual([err1, err2, err3]);
+                        done();
+                    })
+                });
+
+            });
+
         });
 
         describe('settle', () => {