.when() documentation should say it takes Promises, not just Deferreds

[JonathanAquino]

The documentation for $.when() says that it takes Deferreds. However, it later implies that it can take Deferreds or Promises:

If a single argument is passed to jQuery.when() and it is not a Deferred or a Promise, ...

If so, then the documentation should be updated to say that $.when() takes Promises, not just Deferreds. Promises are more general than Deferreds.

In my testing, $.when() works with Promises, not just Deferreds.

[dmethvin]

Yep, that's a feature of version 3.0.0 which hasn't been released yet. I don't see a commit in the 3.0 api docs branch yet though so thanks for the reminder! There is a mention of it in the 3.0 upgrade guide already, which is taking shape here.

If you'd like to help by reviewing the major issues there and creating pull requests for the docs that would be much appreciated. Also you have comment on the upgrade guide draft so any input there is welcome too.

Edit: ref jquery/jquery#1722

[JonathanAquino]

@dmethvin Actually my comment applies to jQuery 2. You can not only pass Deferreds to .when() - you can also pass promises from Deferred.promise(). Promises are more general than Deferreds.

That is why I think the documentation for $.when() should say that it takes Promises, not just Deferreds.

[dmethvin]

Oh you mean the .promise from our own jQuery.Deferred? Yes. I agree, the type of the incoming args there should be Promise and not Deferred.

[AurelioDeRosa]

Deferred is a superset of Promise, or to cite our own documentation:

The Promise exposes only the Deferred methods needed to attach additional handlers or determine the state

Said that, $.when() accepts Deferred, Promise, and Promise-like objects. In fact, in the documentation page of $.when(), we show an example where we pass $.ajax( "test.aspx" ) which returns an jqXHR object, which in turn is a Promise-like object.

In conclusion, I think we should specify all these types and not replace Deferred with Promise.

[JonathanAquino]

@AurelioDeRosa Since Deferred is a superset of Promise, then if you say that $.when accepts Promise-like objects, that includes Deferreds, Promises, and Promise-like objects.

So wouldn't it make more sense to just say that $.when accepts Promise-like objects?

[dmethvin]

For jQuery 1.x/2.x it only accepts jQuery.Deferred or the jQuery.Deferred.promise subset of one.

For jQuery 3.0 it also accepts any "thenable" including an ES6 Promise.

We will probably want to change our use of the type name Promise in Types.html to avoid confusion with the now-standard ES6 Promise. We can also add a "Thenable" type.