Fix documentation for JQUERY.AJAX() AND JSONP

[mikesherov]

trafficstars

original ticket: http://bugs.jquery.com/ticket/12362

Related: http://bugs.jquery.com/ticket/

The above bug has been closed but the documentation is now misleading again for jQuery 1.8.0 (critically, 1.5+).

The documentation reads:

error This handler is not called for cross-domain script and JSONP requests.

timeout In Firefox 3.0+ only, script and JSONP requests cannot be cancelled by a timeout; the script will run even if it arrives after the timeout period.

Data types When data is retrieved from remote servers (which is only possible using the script or jsonp data types), the error callbacks and global events will never be fired.

Examples: http://jsfiddle.net/pte5g/14/

[dmethvin]

@jaubourg @mikesherov Can you suggest wording to correct? I'm not clear on what is wrong here.

[cmbuckley]

Related: #8510, #12362, #37.

The documentation for the error callback states:

This handler is not called for cross-domain script and cross-domain JSONP requests.

This was true in jQuery 1.4 but this is no longer the case. As of jQuery 1.5, the error callback is called for cross-domain JSONP requests, but not for cross-domain script requests.

However, when passing a timeout option, the error callback is called if the request times out, regardless of the request type. (I think that was why I included that section in the original bug report, but it's been a while!)

The section "Data types" includes a similar note:

When data is retrieved from remote servers (which is only possible using the script or jsonpdata types), the error callbacks and global events will never be fired.

Again, for jQuery 1.5+, the error callback is now called for cross-domain JSONP requests. The global events don't appear to be fired.

Not sure what the exact wording should be, but hopefully there's enough information to help you decide now :-)

Fiddle: http://jsfiddle.net/cbuckley/pte5g/15/

[jaubourg]

Key here is that there is no error handling in the script transport (because we cannot guarantee consistent behaviour across all browsers). That's why we don't trigger global events, so that the active counter is not corrupted (like it was back in the 1.4 days). The fact errors are better reported for JSONP is a happy accident of the rewrite and, off the top of my hat, I'm certain there are situations where the error is not reported anyway (network errors come to mind IIRC).

I honestly dunno how to document this properly without drowning a newcomer into too many details.

Regarding manual aborts (which timeouts are), they will trigger error handlers no matter what just because they're transport agnostic.

FYI, I intend to deal with error handling in the 2.x line (should be doable consistently there).