Documentation improvement

[seregazhuk]

This PR provides some suggestion for documentation improvement:

Promise\race().

Returns a promise which is resolved in the same way the first settled promise resolves

Word resolves confused me that race() returns a promise that resolves once the first promise from the set resolves. But actually, it resolves once the first promise settles. If the settled promise resolves the resulting promise resolves with its resolution value, otherwise it resolves with a rejection reason.

Promise\some()

It is not explicitly said if it expects the exact number of promises to be resolved or at least of this number. I've also added that the resolution value of the resulting promise contains resolution values from the promises that were resolved first.

Maybe these suggestions look like salt is salty, but I think that documentation should be as explicit as possible.

[jsor]

Thanks, that's definitely something which can be improved 👍
The new wording though actually feels more confusing to me. Note, that resolved is not the same as fulfilled. A good explanation of the different adjectives can be found at https://github.com/domenic/promises-unwrapping/blob/master/docs/states-and-fates.md

[seregazhuk]

@jsor Thank you for your feedback. Now I see that React\Promise\some() description was perfectly fine 🤦‍♂️ So, I've left improvement only for React\Promise\some().

[jsor]

at least is wrong here. The output promise fulfills after exactly $howManyfulfill and ignores the rest.

[seregazhuk]

I've replaced word resolve with fulfill.

My intention with word at least was to show, that it is enough for $howMany promises to be fulfilled. For example, when we have 3 pending promises, it is enough for 2 of them to be fulfilled. Not exactly 2 should be fulfilled, and 1 should fail.

[seregazhuk]

I'm still a bit confused about statuses. Documentation says that Deferred::resolve() resolves the promise and Deferred::reject() rejects the promise. But according this doc rejected promise is also resolved:

A promise is resolved if it ... has been fulfilled or rejected

Does this mean that Deferred::resolve() actually fulfills the promise? Or words resolved and fulfilled can sometimes be interchangeable?

[jsor]

That sentence is wrong and we should probably rework the whole documentation to use the correct adjectives :)

resolved means, the promise's fate is sealed and any subsequent calls to resolve() and reject() have no effect. But that doesn't mean the promise is settled because it might follow another promise (resolve($anotherPromise)) which itself is still pending. Then the promise will settle once $anotherPromise settles.

[seregazhuk]

Now I see :) Thanks for clarifying 👍

[WyriHaximus]

ping @clue

[clue]

@seregazhuk Thanks for your patience, changes LGTM 👍 Can you squash this into a single commit?

[seregazhuk]

@clue Done!

[clue]