javascript - jQuery 1.8 中的 pipe() 和 then() 文档与现实

Question

更新:这个问题现在已经过时了，因为文档是准确的并且是最新的。

我一直在研究 jQuery Deferred/Promise API，我对 pipe() 和 then() 在哲学上和在 jQuery 文档中。我发现从 jQuery 1.8 开始，pipe() 只是 then() 的别名。

来自 jQuery 源代码:

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

然而，pipe() 和 then() 的文档完全不同，因为它们的用途可能完全不同。

then() 的说明:

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

pipe() 的说明:

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

我知道从历史上看他们的行为略有不同，但在整个documentation for pipe或 documentation for then ，它甚至没有说这两个函数现在做完全相同的事情。

所以，这是我的两部分问题:

1. 为什么 pipe() 和 then() 之间的文档在 jQuery 1.8 中有所不同？
2. 为什么 then() 返回一个新 延迟对象？此行为完全没有记录(docs just say it returns a Deferred, not that it's a new one)。我知道这样做很有用(即实现 pipe() 的所有功能)，但从哲学上讲为什么会这样？鉴于 then() 的描述(附加处理程序)，这是不必要的。

更新

我什至会说 then() 文档具有误导性和不准确:

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

也许它只是含糊不清，但它暗示它会返回您为链接调用 then() 的延迟对象，而实际上它会返回一个全新的对象....

再次更新

似乎文档完全错误/过时了!所以这回答了为什么文档没有提到它们是同一件事。但是，我的第二个问题仍然存在。 then() 返回一个 new 的原因是否只是为了使它和 pipe() 等价？

Answer 1

jQuery 1.8 的文档更新尚未在线。

根据 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.

更新是的，then() 返回一个新的Deferred 因为it is equivalent to pipe() now .我非常有信心文档更新会很快澄清这一点。

完整性的进一步更新:最近更新了文档，现在说 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.

对于 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.