pipe() and then() documentation vs reality in jQuery 1.8

Question

Update: This question is now out of date as the documentation is accurate and up to date.

I\'ve been exploring the jQuery Deferred/Promise API for a bit and I\'m v

Answer 1

The documentation update for jQuery 1.8 is not online yet.

According to this recent blog post:

We’re in the process of updating the API documentation for all the changes to 1.8, but for now you can refer back to the changelog in the jQuery 1.8 announcement to see what’s changed.

Update: Yes, then() returns a new Deferred because it is equivalent to pipe() now. I'm pretty confident the documentation update will clarify this soon.

Further update for completeness: The documentation was recently updated and now says for pipe():

Deprecation Notice: As of jQuery 1.8, the deferred.pipe() method is deprecated. The deferred.then() method, which replaces it, should be used instead.

And for then():

Prior to jQuery 1.8, the arguments could be a function or an array of functions.

[...]

As of jQuery 1.8, the deferred.then() method returns a new promise that can filter the status and values of a deferred through a function, replacing the now-deprecated deferred.pipe() method. The doneFilter and failFilter functions filter the original deferred's resolved / rejected status and values. The progressFilter function filters any calls to the original deferred's notify or notifyWith methods. These filter functions can return a new value to be passed along to the promise's .done() or .fail() callbacks, or they can return another observable object (Deferred, Promise, etc) which will pass its resolved / rejected status and values to the promise's callbacks. If the filter function used is null, or not specified, the promise will be resolved or rejected with the same values as the original.