Add docblocks to functions and interfaces

src/CancellablePromiseInterface.php

@@ -5,6 +5,12 @@
 interface CancellablePromiseInterface extends PromiseInterface
 {
     /**
+     * The `cancel()` method notifies the creator of the promise that there is no
+     * further interest in the results of the operation.
+     *
+     * Once a promise is settled (either fulfilled or rejected), calling `cancel()` on
+     * a promise has no effect.
+     *
      * @return void
      */
     public function cancel();

src/ExtendedPromiseInterface.php

@@ -5,24 +5,92 @@
 interface ExtendedPromiseInterface extends PromiseInterface
 {
     /**
+     * Consumes the promise's ultimate value if the promise fulfills, or handles the
+     * ultimate error.
      *
-     * The `$onProgress` argument is deprecated and should not be used anymore.
+     * It will cause a fatal error if either `$onFulfilled` or
+     * `$onRejected` throw or return a rejected promise.
      *
+     * Since the purpose of `done()` is consumption rather than transformation,
+     * `done()` always returns `null`.
+     *
+     * @param callable|null $onFulfilled
+     * @param callable|null $onRejected
+     * @param callable|null $onProgress This argument is deprecated and should not be used anymore.
      * @return void
      */
     public function done(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);
 
     /**
+     * Registers a rejection handler for promise. It is a shortcut for:
+     *
+     * ```php
+     * $promise->then(null, $onRejected);
+     * ```
+     *
+     * Additionally, you can type hint the `$reason` argument of `$onRejected` to catch
+     * only specific errors.
+     *
+     * @param callable $onRejected
      * @return ExtendedPromiseInterface
      */
     public function otherwise(callable $onRejected);
 
     /**
+     * Allows you to execute "cleanup" type tasks in a promise chain.
+     *
+     * It arranges for `$onFulfilledOrRejected` to be called, with no arguments,
+     * when the promise is either fulfilled or rejected.
+     *
+     * * If `$promise` fulfills, and `$onFulfilledOrRejected` returns successfully,
+     *    `$newPromise` will fulfill with the same value as `$promise`.
+     * * If `$promise` fulfills, and `$onFulfilledOrRejected` throws or returns a
+     *    rejected promise, `$newPromise` will reject with the thrown exception or
+     *    rejected promise's reason.
+     * * If `$promise` rejects, and `$onFulfilledOrRejected` returns successfully,
+     *    `$newPromise` will reject with the same reason as `$promise`.
+     * * If `$promise` rejects, and `$onFulfilledOrRejected` throws or returns a
+     *    rejected promise, `$newPromise` will reject with the thrown exception or
+     *    rejected promise's reason.
+     *
+     * `always()` behaves similarly to the synchronous finally statement. When combined
+     * with `otherwise()`, `always()` allows you to write code that is similar to the familiar
+     * synchronous catch/finally pair.
+     *
+     * Consider the following synchronous code:
+     *
+     * ```php
+     * try {
+     *     return doSomething();
+     * } catch(\Exception $e) {
+     *     return handleError($e);
+     * } finally {
+     *     cleanup();
+     * }
+     * ```
+     *
+     * Similar asynchronous code (with `doSomething()` that returns a promise) can be
+     * written:
+     *
+     * ```php
+     * return doSomething()
+     *     ->otherwise('handleError')
+     *     ->always('cleanup');
+     * ```
+     *
+     * @param callable $onFulfilledOrRejected
      * @return ExtendedPromiseInterface
      */
     public function always(callable $onFulfilledOrRejected);
 
     /**
+     * Registers a handler for progress updates from promise. It is a shortcut for:
+     *
+     * ```php
+     * $promise->then(null, null, $onProgress);
+     * ```
+     *
+     * @param callable $onProgress
      * @return ExtendedPromiseInterface
      * @deprecated 2.6.0 Progress support is deprecated and should not be used anymore.
      */

src/PromiseInterface.php

@@ -5,9 +5,36 @@
 interface PromiseInterface
 {
     /**
+     * Transforms a promise's value by applying a function to the promise's fulfillment
+     * or rejection value. Returns a new promise for the transformed result.
      *
-     * The `$onProgress` argument is deprecated and should not be used anymore.
+     * The `then()` method registers new fulfilled and rejection handlers with a promise
+     * (all parameters are optional):
      *
+     *  * `$onFulfilled` will be invoked once the promise is fulfilled and passed
+     *     the result as the first argument.
+     *  * `$onRejected` will be invoked once the promise is rejected and passed the
+     *     reason as the first argument.
+     *  * `$onProgress` (deprecated) will be invoked whenever the producer of the promise
+     *     triggers progress notifications and passed a single argument (whatever it
+     *     wants) to indicate progress.
+     *
+     * It returns a new promise that will fulfill with the return value of either
+     * `$onFulfilled` or `$onRejected`, whichever is called, or will reject with
+     * the thrown exception if either throws.
+     *
+     * A promise makes the following guarantees about handlers registered in
+     * the same call to `then()`:
+     *
+     *  1. Only one of `$onFulfilled` or `$onRejected` will be called,
+     *      never both.
+     *  2. `$onFulfilled` and `$onRejected` will never be called more
+     *      than once.
+     *  3. `$onProgress` (deprecated) may be called multiple times.
+     *
+     * @param callable|null $onFulfilled
+     * @param callable|null $onRejected
+     * @param callable|null $onProgress This argument is deprecated and should not be used anymore.
      * @return PromiseInterface
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null, callable $onProgress = null);

src/PromisorInterface.php

@@ -5,6 +5,8 @@
 interface PromisorInterface
 {
     /**
+     * Returns the promise of the deferred.
+     *
      * @return PromiseInterface
      */
     public function promise();

src/functions.php

@@ -2,6 +2,20 @@
 
 namespace React\Promise;
 
+/**
+ * Creates a promise for the supplied `$promiseOrValue`.
+ *
+ * If `$promiseOrValue` is a value, it will be the resolution value of the
+ * returned promise.
+ *
+ * If `$promiseOrValue` is a thenable (any object that provides a `then()` method),
+ * a trusted promise that follows the state of the thenable is returned.
+ *
+ * If `$promiseOrValue` is a promise, it will be returned as is.
+ *
+ * @param mixed $promiseOrValue
+ * @return PromiseInterface
+ */
 function resolve($promiseOrValue = null)
 {
     if ($promiseOrValue instanceof ExtendedPromiseInterface) {
@@ -25,6 +39,22 @@ function resolve($promiseOrValue = null)
     return new FulfilledPromise($promiseOrValue);
 }
 
+/**
+ * Creates a rejected promise for the supplied `$promiseOrValue`.
+ *
+ * If `$promiseOrValue` is a value, it will be the rejection value of the
+ * returned promise.
+ *
+ * If `$promiseOrValue` is a promise, its completion value will be the rejected
+ * value of the returned promise.
+ *
+ * This can be useful in situations where you need to reject a promise without
+ * throwing an exception. For example, it allows you to propagate a rejection with
+ * the value of another promise.
+ *
+ * @param mixed $promiseOrValue
+ * @return PromiseInterface
+ */
 function reject($promiseOrValue = null)
 {
     if ($promiseOrValue instanceof PromiseInterface) {
@@ -36,13 +66,32 @@ function reject($promiseOrValue = null)
     return new RejectedPromise($promiseOrValue);
 }
 
+/**
+ * Returns a promise that will resolve only once all the items in
+ * `$promisesOrValues` have resolved. The resolution value of the returned promise
+ * will be an array containing the resolution values of each of the items in
+ * `$promisesOrValues`.
+ *
+ * @param array $promisesOrValues
+ * @return PromiseInterface
+ */
 function all($promisesOrValues)
 {
     return map($promisesOrValues, function ($val) {
         return $val;
     });
 }
 
+/**
+ * Initiates a competitive race that allows one winner. Returns a promise which is
+ * resolved in the same way the first settled promise resolves.
+ *
+ * The returned promise will become **infinitely pending** if  `$promisesOrValues`
+ * contains 0 items.
+ *
+ * @param array $promisesOrValues
+ * @return PromiseInterface
+ */
 function race($promisesOrValues)
 {
     $cancellationQueue = new CancellationQueue();
@@ -66,6 +115,20 @@ function race($promisesOrValues)
     }, $cancellationQueue);
 }
 
+/**
+ * Returns a promise that will resolve when any one of the items in
+ * `$promisesOrValues` resolves. The resolution value of the returned promise
+ * will be the resolution value of the triggering item.
+ *
+ * The returned promise will only reject if *all* items in `$promisesOrValues` are
+ * rejected. The rejection value will be an array of all rejection reasons.
+ *
+ * The returned promise will also reject with a `React\Promise\Exception\LengthException`
+ * if `$promisesOrValues` contains 0 items.
+ *
+ * @param array $promisesOrValues
+ * @return PromiseInterface
+ */
 function any($promisesOrValues)
 {
     return some($promisesOrValues, 1)
@@ -74,6 +137,24 @@ function any($promisesOrValues)
         });
 }
 
+/**
+ * Returns a promise that will resolve when `$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.
+ *
+ * The returned promise will reject if it becomes impossible for `$howMany` items
+ * to resolve (that is, when `(count($promisesOrValues) - $howMany) + 1` items
+ * reject). The rejection value will be an array of
+ * `(count($promisesOrValues) - $howMany) + 1` rejection reasons.
+ *
+ * The returned promise will also reject with a `React\Promise\Exception\LengthException`
+ * if `$promisesOrValues` contains less items than `$howMany`.
+ *
+ * @param array $promisesOrValues
+ * @param int $howMany
+ * @return PromiseInterface
+ */
 function some($promisesOrValues, $howMany)
 {
     $cancellationQueue = new CancellationQueue();
@@ -140,6 +221,17 @@ function some($promisesOrValues, $howMany)
     }, $cancellationQueue);
 }
 
+/**
+ * Traditional map function, similar to `array_map()`, but allows input to contain
+ * promises and/or values, and `$mapFunc` may return either a value or a promise.
+ *
+ * The map function receives each item as argument, where item is a fully resolved
+ * value of a promise or value in `$promisesOrValues`.
+ *
+ * @param array $promisesOrValues
+ * @param callable $mapFunc
+ * @return PromiseInterface
+ */
 function map($promisesOrValues, callable $mapFunc)
 {
     $cancellationQueue = new CancellationQueue();
@@ -178,6 +270,17 @@ function ($mapped) use ($i, &$values, &$toResolve, $resolve) {
     }, $cancellationQueue);
 }
 
+/**
+ * Traditional reduce function, similar to `array_reduce()`, but input may contain
+ * promises and/or values, and `$reduceFunc` may return either a value or a
+ * promise, *and* `$initialValue` may be a promise or a value for the starting
+ * value.
+ *
+ * @param array $promisesOrValues
+ * @param callable $reduceFunc
+ * @param mixed $initialValue
+ * @return PromiseInterface
+ */
 function reduce($promisesOrValues, callable $reduceFunc, $initialValue = null)
 {
     $cancellationQueue = new CancellationQueue();
@@ -215,7 +318,9 @@ function reduce($promisesOrValues, callable $reduceFunc, $initialValue = null)
     }, $cancellationQueue);
 }
 
-// Internal functions
+/**
+ * @internal
+ */
 function _checkTypehint(callable $callback, $object)
 {
     if (!\is_object($object)) {