Documentation suggests finally() will handle rejected promise

[lucasnetau]

Unless I'm reading it wrong, the documentation appears to have an issue with unhandled rejected promises.

A rejected promise will be considered "handled" if you catch the rejection reason with either the then() method, the catch() method, or the finally() method. Note that each of these methods return a new promise that may again be rejected if you re-throw an exception.

However if you are only using a finally() method it will not be considered handled() by the current implementation and an Unhandled promise rejection will be thrown.

<?php declare(strict_types = 1);

use React\EventLoop\Loop;
use React\Promise\Deferred;

require_once __DIR__ . '/../vendor/autoload.php';

$deferred = new Deferred(function() use (&$deferred) {
    $deferred->reject(new \RuntimeException('Request cancelled'));
});

$promise = $deferred->promise();

$promise->finally(function() {
    Loop::stop();
});

Loop::get()->futureTick(function () use (&$deferred) {
    $deferred->reject(new \RuntimeException('Error'));
});

Loop::get()->run();

[clue]

@lucasnetau Thanks for reporting, I can see where you're coming from and agree the documentation could be improved 👍

Technically, the finally() method does indeed mark the original promise "handled" – however, it will also return a new child promise that will not be marked "handled" automatically. As a result, you would still see the same "unhandled promise rejection" even if it may be coming from a different promise. I can see why this would be confusing behavior and hard to read from the current documentation. This behavior is also covered by a number of tests in #248 and #249.

I hope this helps! I believe this has been answered, so I'll close this for now. That said, I agree we may want to improve the documentation. PRs welcome I guess?