Improve documentation for `converters`

[KES777]

DOC

There is no description what "text html": true does

Also extend the example:

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function( result ) {
      // Do stuff
      return newresult;
    }
  }
});

by adding dataType: 'json', to be explicit that callback expects json format

Current documentation lead to missread. As result I get this

[dmethvin]

For reference, the existing docs are at http://api.jquery.com/jquery.ajax/ under Using Converters.

Additional background: https://forum.jquery.com/topic/understanding-ajax-converters

What additional clarification would you like? We could add something like "The converter "text html": true indicates that the left type text can be treated as the right type html with no additional processing."

However, I am not sure that would have provided the information you needed for your StackOverflow question. Did it appear you needed a custom data type in order to receive JSON format? As you can tell, the documentation for $.ajax is very long, so adding deep discussion on this page about rarely-used details sometimes makes the issue worse since few will read it thoroughly.

[KES777]

My task were to send and receive data in custom format. After receiving data it should be in json format. JSON because it is native to javascript object and easy to work.

For example it can be documented as:

convertes specify direction for data convertion. 'text json' specify that received response will be converted from text to json. Specified function will do conversion job. By default for text json conversion jQuery.parseJSON is used. If you want to leave data as is, but want to change type, you can use true instead of function. This is same as function(data){return data} and default for text html conversion.

Currently for dataType doc is:

jQuery can convert a dataType from what it received in the Content-Type header to what you require. For example, if you want a text response to be treated as XML, use "text xml" for the dataType. You can also make a JSONP request, have it received as text, and interpreted by jQuery as XML: "jsonp text xml". Similarly, a shorthand string such as "jsonp xml" will first attempt to convert from jsonp to xml, and, failing that, convert from jsonp to text, and then from text to xml.

To be honest I do not understand what this speaks about. For example:

if you want a text response to be treated as XML, use "text xml" for the dataType

But to specify how it should be converted I must use convertes, must not? For next sentence same: How and why dataType (which should hold type of expected data) take convertion task?

Also this part describes six types of data, but do not mention how to provide custom, is it allowed and how it would work.

finally Using converters doc section mix understanding. To convert the response mycustomtype to json format I should write:

$.ajax({
  contents: {
    mycustomtype: /mycustomtype/
  },
  dataType: 'mycustomtype',
  converters: {
    "text mycustomtype": jQuery.parseJSON
  }
});

Right? If so, then we can explain: mycustomtype response is unknown to jQuery and counted as text by default. Therefore we should write converter text mycustomtype which will return object representing response, or, as showed in example above, JSON object.

The second example in DOC Using converters can be removed, because it is unclear what task it tries to resolve (convert from a supported type to a custom data type and back again why response should be converted from 'x' to 'json' and again to 'x'? ) and when specified text mycustomtype, mycustomtype json converters are triggered.

My problem were that I get response in mycustomtype and can not understand why mycustomtype json converter is not triggered.

Also in this part is not clear why .ajaxSetup is used for .ajax fuction? Typo?

**Sorry for my English, I am not native speaker. Hope my explanation is clear

[KES777]

Documentation also does not cover this case:

$.ajax( url, {
    accepts: { dload: 'application/x-dload' },
    contents: { dload: /dload/ },
    converters: {
        "text dload": jQuery.parseJSON,
        "xml dload": convert_xml_to_dload,
        "html dload": convert_html_to_dload,
    },
    dataType: 'dload',
    success: function( data, status, xhr ){
        ... data is of dload type
    },
})

here text dload always called, despite on Content-Type is text/html. If I comment out text dload line then xml dload html dload are called as expected. But for this case when Content-Type is application/x-dload the data is not converted to object and passed as string. dload dload converter does not work =(

[KES777]

oh, I was wrong. jQuery just get first defined key and call its convertor:

Here always json dload converter will be called:

		accepts: { dload: 'application/x-dload' },
		contents: { dload: /dload/ },
		converters: {
			'json dload': true,
			'html dload': function( data ) {
				return { html: data }
			},
		},
		dataType: 'dload',

Here always html dload converter will be called:

		accepts: { dload: 'application/x-dload' },
		contents: { dload: /dload/ },
		converters: {
			'html dload': function( data ) {
				return { html: data }
			},
			'json dload': true,
		},
		dataType: 'dload',

despite on that response Content-Type is application/json or text/html