Deferred.then() documentation needs more emphasis on chaining of Deferreds/Promises

The documentation for Deferred.then() states:

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.

The fact that the filter functions can return a new Deferred or Promise, and the importance of that is greatly under emphasized. The way it is written seems like a small unimportatnt side note, but important functionality is not clear due to the sublety of the statement. And that functionality being that you can, for example, chain together multiple functions (returning Promises) which will not execute until the previous promise has been resolved.

Let me give an example of why this feature needs to be more strongly emphasized:

I recently ran into a situation where I was displaying validation errors and "OK, Cancel"-style dialogs using jQuery-ui dialogs. As we all know, the callbacks for the dialogs are asynchronous. Therefore, I needed further validation to wait until the user had clicked a button on one of the dialogs, and depending on the action taken by the user, halt all remaining validation.

The answer was to break down the validation into logical sections/functions, and each validation function would create its own Deferred and return a Promise. Then, the jQuery-ui dialogs gets a callback function for the buttons that either resolve or reject the Deferred.

So, basically, you can chain together validation functions which display jQuery-ui dialogs and have them queued as if they were synchronous, and skipping the execution of other validation if one of them rejects its Deferred.

The general use case being:

$.when(validationOneReturningPromise())
.then(validationTwoReturningPromise)
.then(validationThreeReturningPromise)
.done(function() { someForm.submit(); });

This is only one scenario out of many possible that could greatly benefit from clarification and stronger emphasis in this area of the documentation. The features available with when() and then() are quite powerful, but the full extent of the possible uses is, I feel, undersold and underdemonstrated in the docs.

Thank You

Start with the Deferred.then() documentation and review the related $.when() and chaining discussion. Emphasize that filters can return Deferreds or Promises, explain the sequencing and rejection behavior, and include the validation-style example from the issue. Done means the chaining use case and its importance are clear to readers.