Be more unambiguous about the return type jqXhr.then() as opposed to jqXhr.done() or jqXhr.always()

[Infeligo]

jqXhr.done() and jqXhr.always() methods return a jqXhr object while jqXhr.then() returns a promise, which is not that obvious at all.

For example, this code works:

    var jqXhr1 = $.ajax({
        url: "data.json",
        method: "GET",
        dataType: "json"
    }).always(function () {
        console.log("Always 1");
    });

    jqXhr1.abort();

But this doesn't:

    var jqXhr2 = $.ajax({
        url: "data.json",
        method: "GET",
        dataType: "json"
    }).then(function () {
        console.log("Then 2");
    });

    jqXhr2.abort(); // fails, cause it's a promise

[qantourisc]

Just ran into the same issue. Imo it should return a jqXhr compatible object.

[kswedberg]

@jaubourg, @dmethvin : Is this an api inconsistency that should be fixed in core or a documentation problem? If documentation problem, what/where would you suggest we update?

[dmethvin]

I think this is a docs issue. The .then() method consistently returns a new Deferred whether it's a jqXHR or not. This wouldn't be any different than if you used a chain of Promises/A+ objects, you can't reach back into the chain and expect to change something that happened on a previous Promise.