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?