Merge pull request #132 from CharlotteDunoisLabs/patch-docblocks

Add docblocks to functions and interfaces

Author: clue

src/PromiseInterface.php

@@ -5,26 +5,120 @@
 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 `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.
+     *
+     * 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.
+     *
+     * @param callable|null $onFulfilled
+     * @param callable|null $onRejected
      * @return PromiseInterface
      */
     public function then(callable $onFulfilled = null, callable $onRejected = null);
 
     /**
+     * Consumes the promise's ultimate value if the promise fulfills, or handles the
+     * ultimate error.
+     *
+     * It will cause a fatal error (`E_USER_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
      * @return void
      */
     public function done(callable $onFulfilled = null, callable $onRejected = 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 PromiseInterface
      */
     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 PromiseInterface
      */
     public function always(callable $onFulfilledOrRejected);
 
     /**
+     * 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/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 PromiseInterface) {
@@ -23,6 +37,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) {
@@ -34,13 +64,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(array $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(array $promisesOrValues)
 {
     if (!$promisesOrValues) {
@@ -59,6 +108,20 @@ function race(array $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(array $promisesOrValues)
 {
     return some($promisesOrValues, 1)
@@ -67,6 +130,24 @@ function any(array $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(array $promisesOrValues, $howMany)
 {
     if ($howMany < 1) {
@@ -130,6 +211,17 @@ function some(array $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(array $promisesOrValues, callable $mapFunc)
 {
     if (!$promisesOrValues) {
@@ -162,6 +254,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(array $promisesOrValues, callable $reduceFunc, $initialValue = null)
 {
     $cancellationQueue = new Internal\CancellationQueue();