Skip to content

Commit 52576f0

Browse files
jzaeffererjzaefferer
committed
Document jQuery.ajax's function types and extend xslt accordingly. Fixes jquery#33 - Parameter Listing for Higher-Order Functions
1 parent f6075c2 commit 52576f0

File tree

2 files changed

+116
-8
lines changed

2 files changed

+116
-8
lines changed

‎entries/jQuery.ajax.xml

+22-7
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,37 @@
1+
<?xml version="1.0"?>
2+
<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
13
<entry type='method' name="jQuery.ajax" return="jqXHR">
24
<title>jQuery.ajax()</title>
35
<signature>
46
<added>1.5</added>
57
<argument name="url" type="String">
68
<desc>A string containing the URL to which the request is sent.</desc>
79
</argument>
8-
<argument name="settings" type="Map" optional="true">
10+
<argument name="settings" type="PlainObject" optional="true">
911
<desc>A set of key/value pairs that configure the Ajax request. All settings are optional. A default can be set for any option with <a href="/jQuery.ajaxSetup">$.ajaxSetup()</a>. See <a href="#jQuery-ajax-settings">jQuery.ajax( settings )</a> below for a complete list of all settings. </desc>
1012
</argument>
1113
</signature>
1214
<signature>
1315
<added>1.0</added>
14-
<argument name="settings" type="Map" optional="true">
16+
<argument name="settings" type="PlainObject" optional="true">
1517
<desc>A set of key/value pairs that configure the Ajax request. All settings are optional. A default can be set for any option with <a href="/jQuery.ajaxSetup">$.ajaxSetup()</a>.</desc>
1618
<option default="depends on DataType" name="accepts" type="PlainObject">
1719
<desc>The content type sent in the request header that tells the server what kind of response it will accept in return. If the <code>accepts</code> setting needs modification, it is recommended to do so once in the <code>$.ajaxSetup()</code> method.</desc>
1820
</option>
1921
<option default="true" name="async" type="Boolean">
2022
<desc>By default, all requests are sent asynchronously (i.e. this is set to <code>true</code> by default). If you need synchronous requests, set this option to <code>false</code>. Cross-domain requests and <code>dataType: "jsonp"</code> requests do not support synchronous operation. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active. <strong>As of jQuery 1.8, the use of <code> async: false </code> is deprecated.</strong></desc>
2123
</option>
22-
<option name="beforeSend(jqXHR, settings)" type="Function">
24+
<option name="beforeSend" type="Function">
25+
<argument name="jqXHR" type="jqXHR" />
26+
<argument name="settings" type="PlainObject" />
2327
<desc>A pre-request callback function that can be used to modify the jqXHR (in jQuery 1.4.x, XMLHTTPRequest) object before it is sent. Use this to set custom headers, etc. The jqXHR and settings maps are passed as arguments. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>. Returning <code>false</code> in the <code>beforeSend</code> function will cancel the request. <strong>As of jQuery 1.5</strong>, the <code>beforeSend</code> option will be called regardless of the type of request.</desc>
2428
</option>
2529
<option name="cache" default="true, false for dataType 'script' and 'jsonp'" type="Boolean">
2630
<desc>If set to <code>false</code>, it will force requested pages not to be cached by the browser. <strong>Note:</strong> Setting <code>cache</code> to false will only work correctly with HEAD and GET requests. It works by appending "_={timestamp}" to the GET parameters. The parameter is not needed for other types of requests, except in IE8 when a POST is made to a URL that has already been requested by a GET.</desc>
2731
</option>
28-
<option name="complete(jqXHR, textStatus)" type="Function, Array">
32+
<option name="complete" type="Function">
33+
<argument name="jqXHR" type="jqXHR" />
34+
<argument name="textStatus" type="String" />
2935
<desc>A function to be called when the request finishes (after <code>success</code> and <code>error</code> callbacks are executed). The function gets passed two arguments: The jqXHR (in jQuery 1.4.x, XMLHTTPRequest) object and a string categorizing the status of the request (<code>"success"</code>, <code>"notmodified"</code>, <code>"error"</code>, <code>"timeout"</code>, <code>"abort"</code>, or <code>"parsererror"</code>). <strong>As of jQuery 1.5</strong>, the <code>complete</code> setting can accept an array of functions. Each function will be called in turn. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
3036
</option>
3137
<option name="contents" type="PlainObject" added="1.5">
@@ -51,7 +57,10 @@
5157
<option name="data" type="Object, String">
5258
<desc>Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests. See <code>processData</code> option to prevent this automatic processing. Object must be Key/Value pairs. If value is an Array, jQuery serializes multiple values with same key based on the value of the <code>traditional</code> setting (described below).</desc>
5359
</option>
54-
<option name="dataFilter(data, type)" type="Function">
60+
<option name="dataFilter" type="Function">
61+
<argument name="data" type="Object" />
62+
<argument name="type" type="String" />
63+
<return type="Object"/>
5564
<desc>A function to be used to handle the raw response data of XMLHttpRequest.This is a pre-filtering function to sanitize the response. You should return the sanitized data. The function accepts two arguments: The raw data returned from the server and the 'dataType' parameter.</desc>
5665
</option>
5766
<option name="dataType" default="Intelligent Guess (xml, json, script, or html)" type="String">
@@ -67,7 +76,10 @@
6776
</li>
6877
</ul></desc>
6978
</option>
70-
<option name="error(jqXHR, textStatus, errorThrown)" type="Function">
79+
<option name="error" type="Function">
80+
<argument name="jqXHR" type="jqXHR" />
81+
<argument name="textStatus" type="String" />
82+
<argument name="errorThrown" type="String" />
7183
<desc>A function to be called if the request fails. The function receives three arguments: The jqXHR (in jQuery 1.4.x, XMLHttpRequest) object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides <code>null</code>) are <code>"timeout"</code>, <code>"error"</code>, <code>"abort"</code>, and <code>"parsererror"</code>. When an HTTP error occurs, <code>errorThrown</code> receives the textual portion of the HTTP status, such as "Not Found" or "Internal Server Error." <strong>As of jQuery 1.5</strong>, the <code>error</code> setting can accept an array of functions. Each function will be called in turn. <strong>Note:</strong> <em>This handler is not called for cross-domain script and JSONP requests.</em> This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>. </desc>
7284
</option>
7385
<option default="true" name="global" type="Boolean">
@@ -113,7 +125,10 @@
113125
<p>If the request is successful, the status code functions take the same parameters as the success callback; if it results in an error, they take the same parameters as the <code>error</code> callback.</p>
114126
</desc>
115127
</option>
116-
<option name="success(data, textStatus, jqXHR)" type="Function, Array">
128+
<option name="success" type="Function">
129+
<argument name="data" type="Object" />
130+
<argument name="textStatus" type="String" />
131+
<argument name="jqXHR" type="jqXHR" />
117132
<desc>A function to be called if the request succeeds. The function gets passed three arguments: The data returned from the server, formatted according to the <code>dataType</code> parameter; a string describing the status; and the <code>jqXHR</code> (in jQuery 1.4.x, XMLHttpRequest) object. <strong>As of jQuery 1.5</strong>, <em>the success setting can accept an array of functions. Each function will be called in turn.</em> This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
118133
</option>
119134
<option name="timeout" type="Number">

‎entries2html.xsl

+94-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@
99
<xsl:if test="@deprecated"> <span class="deprecated">(deprecated <xsl:value-of select="@deprecated" />)</span></xsl:if>
1010
<xsl:if test="@removed"> <span class="removed">(removed <xsl:value-of select="@removed" />)</span></xsl:if>
1111
<span class="type">
12-
<a href="http://api.jquery.com/Types#{@type}"><xsl:value-of select="@type" /></a>
12+
<xsl:text>: </xsl:text>
13+
<xsl:call-template name="render-types" />
1314
</span>
1415
</h5>
1516
<xsl:if test="@default">
@@ -20,6 +21,98 @@
2021
</p>
2122
</xsl:template>
2223

24+
<!--
25+
Render type(s) for a parameter or argument element.
26+
Type can either by a @type attribute or one or more <type> child elements.
27+
-->
28+
<xsl:template name="render-types">
29+
<xsl:if test="@type and type">
30+
<strong>ERROR: Use <i>either</i> @type or type elements</strong>
31+
</xsl:if>
32+
33+
<!-- a single type -->
34+
<xsl:if test="@type">
35+
<xsl:call-template name="render-type">
36+
<xsl:with-param name="typename" select="@type" />
37+
</xsl:call-template>
38+
</xsl:if>
39+
40+
<!-- elements. Render each type, comma seperated -->
41+
<xsl:if test="type">
42+
<xsl:for-each select="type">
43+
<xsl:if test="position() &gt; 1">, </xsl:if>
44+
<xsl:call-template name="render-type">
45+
<xsl:with-param name="typename" select="@name" />
46+
</xsl:call-template>
47+
</xsl:for-each>
48+
</xsl:if>
49+
</xsl:template>
50+
51+
<xsl:template name="render-return-types">
52+
<xsl:if test="@return and return">
53+
<strong>ERROR: Use <i>either</i> @return or return element</strong>
54+
</xsl:if>
55+
56+
<!-- return attribute -->
57+
<xsl:if test="@return">
58+
<xsl:call-template name="render-type">
59+
<xsl:with-param name="typename" select="@return" />
60+
</xsl:call-template>
61+
</xsl:if>
62+
63+
<!-- a return element -->
64+
<xsl:if test="return">
65+
<xsl:for-each select="return">
66+
<xsl:if test="position() &gt; 1">
67+
<strong>ERROR: A single return element is expected</strong>
68+
</xsl:if>
69+
<xsl:call-template name="render-types" />
70+
</xsl:for-each>
71+
</xsl:if>
72+
</xsl:template>
73+
74+
<!-- Render a single type -->
75+
<xsl:template name="render-type">
76+
<xsl:param name="typename"/>
77+
<xsl:choose>
78+
<!--
79+
If the type is "Function" we special case and write the function signature,
80+
e.g. function(String)=>String
81+
- formal arguments are child elements to the current element
82+
- the return element is optional
83+
-->
84+
<xsl:when test="$typename = 'Function'">
85+
<text>Function(</text>
86+
<xsl:for-each select="argument">
87+
<xsl:if test="position() &gt; 1">, </xsl:if>
88+
<xsl:value-of select="@name" />
89+
<xsl:text>: </xsl:text>
90+
<xsl:call-template name="render-types" />
91+
</xsl:for-each>
92+
<text>)</text>
93+
<!-- display return type if present -->
94+
<xsl:if test="return or @return">
95+
=>
96+
<xsl:call-template name="render-return-types" />
97+
</xsl:if>
98+
</xsl:when>
99+
<!--
100+
If the type is "Array" and it has child type elements
101+
we display it as "Array of String" (or whatever the sub-type is)
102+
-->
103+
<xsl:when test="$typename = 'Array'">
104+
<xsl:value-of select="$typename"/>
105+
<xsl:if test="type">
106+
<text> of </text>
107+
<xsl:call-template name="render-types" />
108+
</xsl:if>
109+
</xsl:when>
110+
<xsl:otherwise>
111+
<!-- not function - just display typename -->
112+
<a href="http://api.jquery.com/Types#{$typename}"><xsl:value-of select="$typename" /></a>
113+
</xsl:otherwise>
114+
</xsl:choose>
115+
</xsl:template>
23116

24117
<xsl:template match="/">
25118
<xsl:variable name="dquo">"</xsl:variable>

0 commit comments

Comments
 (0)