Class Promise is poorly documented.

[DartBot]

This issue was originally filed by alexe.kaigorodov@gmail.com

---

A Promise can be accomplished in 3 ways: complete, fail, and cancelled. It is not always clear from the documentation, what happens if an attempt is made to accomplish a promise which is already done (e.g.p. promise.fail() for completed promise), and what happens when attempting to take the result of unexistent kind (e.g. Promise.value for failed promise).

More detailed list of questions is as follows:

1. Promise.complete():

"throws an exception if a value has already been provided or the promise
previously completed with an error"

However, the type of exception is not specified.

1. Promise.join():

"Every time one of the promises is computed, it is passed to joinDone."

Nothing is said what happens when the promise has failed or has been cancelled.

1. Promise.waitFor():

"when n promises in arr complete, then cancel the rest of the promises"

Nothing is said what happens when one of the said n promises has failed or has been cancelled.

1. Promise.value:

"It will be null when the promise is in progress (!isDone()), when it was
cancelled (isCancelled()), or when the computed value is actually null."

Nothing is said what happens when the promise has failed.

1. Promise.fail():
   Is it legal to call fail() on cancelled promise? Current implementation allows this, which leads to the situation when isCancelled()==true but call to 'value' throws an exception, while it should return 'null' according to the description of Promise.value.

[DartBot]

This comment was originally written by drfibonacci@google.com

---

Added Area-Library, Triaged labels.

[DartBot]

This comment was originally written by alexe.kaigorodov@gmail.com

---

Additional question:
6. Promise.waitFor():
What value has this promise after completetion?

[sethladd]

Promise was removed, use Future now.

---

Added WontFix label.