Improve documentation

README.md

@@ -420,7 +420,8 @@ $promise = React\Promise\race(array $promisesOrValues);
 ```
 
 Initiates a competitive race that allows one winner. Returns a promise which is
-resolved in the same way the first settled promise resolves.
+resolved in the same way the first settled promise settles. If the settled promise 
+resolves the resulting promise resolves with its resolution value, otherwise it resolves with a rejection reason.
 
 The returned promise will become **infinitely pending** if  `$promisesOrValues`
 contains 0 items.
@@ -447,10 +448,10 @@ if `$promisesOrValues` contains 0 items.
 $promise = React\Promise\some(array $promisesOrValues, integer $howMany);
 ```
 
-Returns a promise that will resolve when `$howMany` of the supplied items in
+Returns a promise that will resolve when at least `$howMany` of the supplied items in
 `$promisesOrValues` resolve. The resolution value of the returned promise
-will be an array of length `$howMany` containing the resolution values of the
-triggering items.
+will be an array of length `$howMany` containing the resolution values of
+`$howMany` resolved promises that were resolved first.
 
 The returned promise will reject if it becomes impossible for `$howMany` items
 to resolve (that is, when `(count($promisesOrValues) - $howMany) + 1` items