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 very confused about the differences between pipe() and then() philosophically and in the jQuery documentation. I've found that pipe() is just an alias for then() as of jQuery 1.8.

From jQuery source:

// Keep pipe for back-compat promise.pipe = promise.then; 

Yet the documentation is completely different for pipe() and then() as they supposedly have entirely different uses.

Description for then():

Description: Add handlers to be called when the Deferred object is resolved or rejected.

Description for pipe():

Description: Utility method to filter and/or chain Deferreds.

I understand that historically they had slightly different behavior, but in the entirety of the documentation for pipe or the documentation for then, it doesn't even say that these two functions do the exact same thing now.

So, here's my two part question:

1. Why does the documentation between pipe() and then() differ as of jQuery 1.8?
2. Why does then() return a new deferred object? This behavior is completely undocumented (the docs just say it returns a Deferred, not that it's a new one). I understand that it has utility in doing so (namely to implement all of pipe()'s features), but philosophically why is it the case? It's unnecessary given the description of then() (to attach handlers).

Update

I'll even go so far as to say the then() docs are misleading and inaccurate:

Since deferred.then returns the deferred object, other methods of the deferred object can be chained to this one, including additional .then() methods.

Maybe it's just vague, but it implies it returns the deferred object you called then() on for chaining, when in reality it returns an entirely new object....

Update Again

Seems the documentation is simply wrong/out of date! So that answers why the documentation makes no mention of them being the same thing. However, my second question still stands. Is the reason then() returns a new deferred simply so that it and pipe() can be made equivalent?

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.