Arguments accessible by .always(), .done() and .fail() from jQuery.ajax()

[peterrow]

Relates to: #49

The documentation is still badly formed. The docs for done(), always() etc.. should describe the params for the function. The page for .ajax is already long winded and I missed the snippet that was reproduced in alano999's post in the above issue.

[dmethvin]

I agree that the ajax docs are long, due to the complexity of the API. How would you suggest editing the page? Can you provide a pull request?

[kswedberg]

@dmethvin : Fixing the ajax docs isn't as important here as fixing the deferred.done/fail/always docs. We need to include params for callback functions, which we're already sort of doing in $.ajax, but not in the others.

[marcandre]

👍

[clayenga]

👍

[lanort]

+1

[dmethvin]

This ticket seems to be a magnet for people providing guidance-free support for .... something. Can one of you offer a pull request or post here a specific set of changes you'd like to see?

[peterrow]

From the original opening post "The docs for done(), always() etc.. should describe the params for the function."

[dmethvin]

Great, then from my reply to the opening post, if you have ideas then please do file a pull request. There are 45 people watching this repo, including me, and it is nicer to them if a notification includes more than a thumbs-up or plus-one.

[peterrow]

Both myself and kswedberg have indicated what is missing from the documentation. It's hard to write the docs when you don't know what the values are.

[dmethvin]

I'm still not sure what you're asking for. The current docs say

jqXHR.done(function( data, textStatus, jqXHR ) {});

Those are the same arguments in the same order as the success callback described earlier in the page. Ditto for .fail(). If you think they need to reference that just file a PR to do so.

[kswedberg]

@dmethvin, The problem is that someone using .done() off of a $.ajax() call could reasonably only look at the docs for .done() (https://api.jquery.com/deferred.done/). Pretty sure the OP is saying that the done/fail/always docs should mention the callback's params when chained off a jqXHR.

[marcandre]

As far as I'm concerned, the current doc is fine now (as @dmethvin points out). It wasn't at the time it was opened. I believe this issue is now resolved. 😄

[peterrow]

@marcandre - where on this page does it mention what the parameters are for the callback functions you pass to done()? https://api.jquery.com/deferred.done/

Answer: It doesn't, but should.

[dmethvin]

The docs already say how it works:

When the Deferred is resolved, doneCallbacks are executed using the arguments provided to the resolve or resolveWith method call in the order they were added

The parameters that are passed to a deferred.done() depend on the parameters passed to deferred.resolve(), and can be anything the caller wants them to be.

If the problem is that people are arriving at the deferred.done() docs and expecting a description of the $.ajax() arguments, then we should put something in https://api.jquery.com/deferred.done/ to the effect of "For information on using .done() with $.ajax, see the jQuery.ajax documentation."

[kswedberg]

@dmethvin : Agreed. that seems like the most sensible course of action here.

[deesto]

This seems kind of important to document, yet it's been a known issue since ... mid 2012?
#49

Please add the function's arguments to the docs, or at least a reference to the fact that the function has arguments? I'm not sure how the information can be considered complete and accurate without at least that reference.

[AurelioDeRosa]

Hi @deesto.

The team is focused on keeping the documentation as accurate and correct as possible. However, as you might know, we work on this in our spare time. Therefore, we always encourage and appreciate any PR that can help us. Would you be keen to submit a PR for this issue?

[rhythmnewt]

I'd like to mention additional caveat for the done() function that should be documented.

If you supply only 1 deferred $.ajax() parameter, then the call back will receive arguments in format (data, textStatus, jqXHR). However if you supply an array of $.ajax(), and use a single callback to handle the results, then the single callback will receive arguments in the array format [[data, textStatus, jqXHR], [data, textStatus, jqXHR]].

This drove me nuts when I had variable number of deferred ajax calls (1 or more).

[dmethvin]

@dimkanewtown That is already documented, see the note on the page: http://api.jquery.com/deferred.always/

[rhythmnewt]

I have hard time translating what is written there into these two cases:

Single $.ajax() call.

$.when($.ajax()).done(function(data, textStatus, jqXHR) {});

vs multiple $.ajax() calls

$.when($.ajax(), $.ajax()).done(function(args[]) {});

Where args[] is a multidimensional array

[0][0] //data
[0][1] //textStatus
[0][2] //jqXHR
[1][0] //data
[1][1] //textStatus
[1][2] //jqXHR

[dmethvin]

The docs for jQuery.when have examples to show what happens. For that case you have two arrays, one for each Deferred, that have the ajax results.

[rhythmnewt]

You're right, $.when documentation describes it to the "t". Was expecting (maybe wrongly) the explanation under done() though. Thanks for the reference.

[dlsso]

So it seems all the information is there, but not necessarily where people are expecting it. I think what we need is someone to rethink the organization and redo it so that parameter info is obvious, or at least easy to get to, no matter which page you're on.

Unfortunately I don't have the depth of knowledge in this area to make the PR myself.