.promise() violates documented behaviour

.promise() violates documented behaviour

Due to the documentation of .promise() the created Deferred object will resolve when all actions bound to the collection have ended.

jQuery's implementation does not behave like that!   (version 1.6 up to 1.8.2)

The documentation still leaves space for two possible interpretations. Both are violated.

Interpretation #1:  For multiple elements the .promise() object resolves once all elements are not being animated at the same time.

The minimal counter example for that meaning is:
  1. $('#foo').fadeOut(100);
  2. var deferred = $('#foo, #bar').promise();
  3. $('#bar').fadeOut(200);
In this example the Deferred is resolved after 100ms. Due to interpretation #1 it must resolve after 200ms.

So let's come to the second possible interpretation.

Interpretation #2:  The .promise()-created object resolves once all currently queued animations have ended.
The minimal counter example is:
  1. $('#foo').fadeOut(100);
  2. var deferred = $('#foo').promise();
  3. $('#foo').fadeIn(200);
In this example the Deferred is resolved after 300ms. Due to interpretation #2 it must resolve after 100ms already.


As we see that both interpretations are wrong - which is the right one?
Or can we modify the documentation to explain it with more details?


Peter