From 24724b4bd1bac6b1b81b9d004715b972b3c6387b Mon Sep 17 00:00:00 2001 From: Charlotte Dunois Date: Tue, 8 Jan 2019 12:57:31 +0100 Subject: [PATCH] Add docblocks to functions and interfaces --- src/CancellablePromiseInterface.php | 6 ++ src/ExtendedPromiseInterface.php | 70 +++++++++++++++++- src/PromiseInterface.php | 29 +++++++- src/PromisorInterface.php | 2 + src/functions.php | 107 +++++++++++++++++++++++++++- 5 files changed, 211 insertions(+), 3 deletions(-) diff --git a/src/CancellablePromiseInterface.php b/src/CancellablePromiseInterface.php index 896db2d3..6b3a8c65 100644 --- a/src/CancellablePromiseInterface.php +++ b/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(); diff --git a/src/ExtendedPromiseInterface.php b/src/ExtendedPromiseInterface.php index 3654177c..13b63691 100644 --- a/src/ExtendedPromiseInterface.php +++ b/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. */ diff --git a/src/PromiseInterface.php b/src/PromiseInterface.php index fcd763d3..edcb0077 100644 --- a/src/PromiseInterface.php +++ b/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); diff --git a/src/PromisorInterface.php b/src/PromisorInterface.php index 9341a4fa..bd644008 100644 --- a/src/PromisorInterface.php +++ b/src/PromisorInterface.php @@ -5,6 +5,8 @@ interface PromisorInterface { /** + * Returns the promise of the deferred. + * * @return PromiseInterface */ public function promise(); diff --git a/src/functions.php b/src/functions.php index c549e4ec..bdbdf52d 100644 --- a/src/functions.php +++ b/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,6 +66,15 @@ 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) { @@ -43,6 +82,16 @@ function all($promisesOrValues) }); } +/** + * 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)) {