jQuery.post( ) .done( ) and success:

jQuery documentation on jQuery.post( )

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.post( "example.php", function() {
  alert( "success" );
})
  .done(function() {
    alert( "second success" );
  })
  .fail(function() {
    alert( "error" );
  })
  .always(function() {
    alert( "finished" );
});

// Perform other work here ...

// Set another completion function for the request above
jqxhr.always(function() {
  alert( "second finished" );
});

What is the difference between the success: parameter and the jqXHR.done( ) method; if there is none, what is the entire point of the jqXHR.done( ) method?

jQuery used to ONLY have the callback functions for success and error and complete.

Then, they decided to support promises with the jqXHR object and that's when they added .done(), .fail(), .always(), etc... in the spirit of the promise API. These new methods serve much the same purpose as the callbacks but in a different form. You can use whichever API style works better for your coding style.

As people get more and more familiar with promises and as more and more async operations use that concept, I suspect that more and more people will move to the promise API over time, but in the meantime jQuery supports both.

The .success() method has been deprecated in favor of the common promise object method names.

From the jQuery doc, you can see how various promise methods relate to the callback types:

> jqXHR.done(function( data, textStatus, jqXHR ) {}); An alternative > construct to the success callback option, the .done() method replaces > the deprecated jqXHR.success() method. Refer to deferred.done() for > implementation details. > > jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {}); An > alternative construct to the error callback option, the .fail() method > replaces the deprecated .error() method. Refer to deferred.fail() for > implementation details. > > jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown ) { > }); An alternative construct to the complete callback option, the > .always() method replaces the deprecated .complete() method. > > In response to a successful request, the function's arguments are the > same as those of .done(): data, textStatus, and the jqXHR object. For > failed requests the arguments are the same as those of .fail(): the > jqXHR object, textStatus, and errorThrown. Refer to deferred.always() > for implementation details. > > jqXHR.then(function( data, textStatus, jqXHR ) {}, function( jqXHR, > textStatus, errorThrown ) {}); Incorporates the functionality of the > .done() and .fail() methods, allowing (as of jQuery 1.8) the > underlying Promise to be manipulated. Refer to deferred.then() for > implementation details.

If you want to code in a way that is more compliant with the ES6 Promises standard, then of these four options you would only use .then().

The reason to prefer Promises over callback functions is to have multiple callbacks and to avoid the problems like Callback Hell.

Callback hell (for more details, refer http://callbackhell.com/): Asynchronous javascript, or javascript that uses callbacks, is hard to get right intuitively. A lot of code ends up looking like this:

asyncCall(function(err, data1){
    if(err) return callback(err);       
    anotherAsyncCall(function(err2, data2){
        if(err2) return calllback(err2);
        oneMoreAsyncCall(function(err3, data3){
            if(err3) return callback(err3);
            // are we done yet?
        });
    });
});

With Promises above code can be rewritten as below:

asyncCall()
.then(function(data1){
    // do something...
    return anotherAsyncCall();
})
.then(function(data2){
    // do something...  
    return oneMoreAsyncCall();    
})
.then(function(data3){
    // the third and final async response
})
.fail(function(err) {
    // handle any error resulting from any of the above calls    
})
.done();

Both .done() and .success() are callback functions and they essentially function the same way.

Here's the documentation. The difference is that .success() is deprecated as of jQuery 1.8. You should use .done() instead.

In case you don't want to click the link:

> Deprecation Notice > > The jqXHR.success(), jqXHR.error(), and jqXHR.complete() callback > methods introduced in jQuery 1.5 are deprecated as of jQuery 1.8. To > prepare your code for their eventual removal, use jqXHR.done(), > jqXHR.fail(), and jqXHR.always() instead.

From the doc:

> jqXHR.done(function( data, textStatus, jqXHR ) {}); > > An alternative construct to the success callback option, the .done() > method replaces the deprecated jqXHR.success() method. Refer to > deferred.done() for implementation details.

The point it is just an alternative for success callback option, and jqXHR.success() is deprecated.