jquery/api.jquery.com — pull request #484 by ExplodingCabbage (2014-04-26 23:10:19+00:00)
Title: jQuery.ajax: rewrite Data Types section

I've rewritten the **Data Types** section because almost every single detail in the whole thing was utterly wrong.

I had some difficulty cleanly writing the paragraph about JSONP, and perhaps it isn't as clear as the others, but it's definitely an improvement on what came before, so I can live with it.

More importantly, there remains significant redundancy of content between the documentation of the `dataType` parameter and the **Data Types** section lower down the page; it may be a good idea to consolidate the two. I'm leaving that for another day, though; removing mass misinformation and slimming down the **Data Types** section in the process is at least a step in the right direction.

Full commit message below...

--------

The "Data Types" was riddled with errors and confusions,
to the point that it was nothing but harmful.

I think this commit fixes all of them. I list them below:

* The first paragraph claimed that all non-XML responses
are treated as text. This is untrue and contradicted
other paragraphs in the same section.

* The third paragraph claimed that XML responses are
passed to the success handler with no 'processing'. This
is untrue (and contradicts the first paragraph); in fact
they are parsed using $.parseXML.

* The third paragraph stated that text and XML responses
were passed to the success handler 'through the
responseText or responseXML property of the jqXHR
object'. While this is not untrue, it is confusing
because it neglects the more obvious and useful way by
which these responses are passed to success and .done
handlers: directly, as the first argument of those
handlers.

* The fourth paragraph was entirely untrue. It claimed that
the Content-Type returned by the server 'must' match the
dataType specified in the settings passed to $.ajax. In
reality, if a dataType is passed to $.ajax, the
Content-Type returned by the server is ignored entirely.

* The fifth paragraph claimed that JavaScript embedded in
HTML responses would be executed automatically before
passing the response to the success handler. This is
untrue. (#482)

* The fifth paragraph additionally claimed that when the
'script' dataType is specified, the response from the
server is not passed to the success handler. This is
also untrue.

* The sixth paragraph contained the confused claim that the
'json' dataType "uses jQuery.parseJSON() when the browser
supports it". This is too confused to even be false; it
is meaningless. jQuery.parseJSON is a jQuery method that
works regardless of whether the browser provides a native
implementation of JSON.parse, and so it is impossible for
the browser to not support it.

* The sixth paragraph additionally contained the questionable
advice "If the fetched data file exists on a remote server,
specify the jsonp type instead [of json]." This seems to
suggest that simply specifying the jsonp dataType will
magically cause the remote server to return a jsonp response
instead of a json response. While this may be true for some
APIs that look for a callback parameter in the request to
decide whether to serve a JSON or JSONP response, it is
certainly not universally true.

* The seventh paragraph stated that the server should form a
valid JSONP response by "prepend[ing] the JSON data with the
callback name". This is almost but not quite correct, and as
such is at best useless and at worst actively misleading.

* The ninth paragraph contained the claim that data can only be
"retrieved from remote servers" when "using the script or
jsonp data types". Firstly, this is potentially confusing if
the reader does not understand that the term 'remote servers'
refers to cross-domain requests, which is a slightly odd usage
(all servers are remote from the client's perspective!)
Secondly, even interpreted as intended, it is untrue, since
$.ajax supports CORS.

This rewrite:

- fixes all of the above issues
- removes first- and second-person pronouns from the copy per
the style guide

Fixes #482