Promote race to when.race public API. Add docs

docs/api.md

@@ -942,11 +942,15 @@ The *competitive race* pattern may be used if one or more of the entire possible
 var promise = when.any(array)
 ```
 
-Initiates a competitive race that allows one winner.  The returned promise will:
+A competitive race that allows one winner.  The returned promise will:
 
 * fulfill as soon as any one of the input promises fulfills, with the value of the fulfilled input promise, *or*
 * reject only if *all* input promises reject, with an array of all the rejection reasons
 
+### See also:
+* [when.race](#whenrace)
+* [when.some](#whensome)
+
 ## when.some
 
 **DEPRECATED**
@@ -955,7 +959,7 @@ Initiates a competitive race that allows one winner.  The returned promise will:
 var promise = when.some(array, n)
 ```
 
-Initiates a competitive race that requires `n` winners.  The returned promise will
+A competitive race that requires `n` winners.  The returned promise will
 
 * fulfill when `n` promises are fulfilled with an array containing the values of the fulfilled input promises, *or*
 * reject when it becomes impossible for `n` promises to become fulfilled (ie when `(array.length - n) + 1` reject) with an array containing the reasons of the rejected input promises
@@ -966,6 +970,25 @@ var remotes = [ping('p2p.cdn.com'), ping('p2p2.cdn.com'), ping('p2p3.cdn.com')];
 when.some(remotes, 2).done(itsAllOk, failGracefully);
 ```
 
+### See also:
+* [when.any](#whenany)
+
+## when.race
+
+```js
+var promise = when.race(array);
+```
+
+A competitive race to settle. The returned promise will settle in the same way as the earliest promise in `array` to settle.  That is, it will
+
+* fulfill if the earliest promise in array fulfills, with the same value, *or*
+* reject if the earliest promise in array rejects, with the same reason.
+
+**WARNING:** As per the ES6 spec, the returned promise will *remain pending forever* if `array` is empty.
+
+### See also:
+* [when.any](#whenany)
+
 # Infinite Promise Sequences
 
 [when.reduce](#whenreduce), [when/sequence](#whensequence), and [when/pipeline](#whenpipeline) are great ways to process asynchronous arrays of promises and tasks.  Sometimes, however, you may not know the array in advance, or may not need or want to process *all* the items in the array.  For example, here are a few situations where you may not know the bounds:

when.js

@@ -49,6 +49,7 @@ define(function (require) {
 
 	when.any         = lift(Promise.any);    // One-winner race
 	when.some        = lift(Promise.some);   // Multi-winner race
+	when.race        = lift(Promise.race);   // First-to-settle race
 
 	when.map         = map;                  // Array.map() for promises
 	when.reduce      = reduce;               // Array.reduce() for promises
@@ -72,8 +73,8 @@ define(function (require) {
 	 *   will be invoked immediately.
 	 * @param {function?} onRejected callback to be called when x is
 	 *   rejected.
-	 * @deprecated @param {function?} onProgress callback to be called when progress updates
-	 *   are issued for x.
+	 * @param {function?} onProgress callback to be called when progress updates
+	 *   are issued for x. @deprecated
 	 * @returns {Promise} a new promise that will fulfill with the return
 	 *   value of callback or errback or the completion value of promiseOrValue if
 	 *   callback and/or errback is not supplied.