jQuery.when: Document changes in 3.0

entries/addClass.xml

@@ -19,6 +19,8 @@
   <desc>Adds the specified class(es) to each element in the set of matched elements.</desc>
   <longdesc>
     <p>It's important to note that this method does not replace a class. It simply adds the class, appending it to any which may already be assigned to the elements.</p>
+    <p>Before jQuery version 3.0, the <code>.addClass()</code> method manipulated the <code>className</code> <em>property</em> of the selected elements, not the <code>class</code> <em>attribute</em>. Once the property was changed, it was the browser that updated the attribute accordingly. An implication of this behavior was that this method only worked for documents with HTML DOM semantics (e.g., not pure XML documents).</p>
+    <p>As of jQuery 3.0 this behavior is changed to improve the support for XML documents, including SVG. Starting from this version, the <code>class</code> <em>attribute</em> is used instead. So, <code>.addClass()</code> can be used on XML or SVG documents.</p>
     <p>More than one class may be added at a time, separated by a space, to the set of matched elements, like so:</p>
     <pre><code>
 $( "p" ).addClass( "myClass yourClass" );

entries/child-selector.xml

@@ -13,7 +13,6 @@
   </signature>
   <desc>Selects all direct child elements specified by "child" of elements specified by "parent".</desc>
   <longdesc>
-    <p>As a CSS selector, the child combinator is supported by all modern web browsers including Safari, Firefox, Opera, Chrome, and Internet Explorer 7 and above, but notably not by Internet Explorer versions 6 and below. However, in jQuery, this selector (along with all others) works across all supported browsers, including IE6.</p>
     <p>The child combinator (E <strong>&gt;</strong> F) can be thought of as a more specific form of the descendant combinator (E F) in that it selects only first-level descendants.</p>
   </longdesc>
   <example>

entries/context.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<entry type="property" name="context" return="Element" deprecated="1.10">
+<entry type="property" name="context" return="Element" deprecated="1.10" removed="3.0">
   <title>.context</title>
   <signature>
     <added>1.3</added>

entries/data.xml

@@ -31,6 +31,7 @@ $( "body" ).data(); // { foo: 52, bar: { myType: "test", count: 40 }, baz: [ 1,
       </code></pre>
       <p>In jQuery 1.4.3 setting an element's data object with <code>.data(obj)</code> extends the data previously stored with that element.</p>
       <p>Prior to jQuery 1.4.3 (starting in jQuery 1.4) the <code>.data()</code> method completely replaced all data, instead of just extending the data object. If you are using third-party plugins it may not be advisable to completely replace the element's data object, since plugins may have also set data.</p>
+      <p><strong>jQuery 3</strong> changes the behavior of this method to align it to the <a href="http://www.w3.org/TR/html5/dom.html#dom-dataset">Dataset API specifications</a>. Specifically, jQuery 3 transforms every two-character sequence of "-" (U+002D) followed by a lowercase ASCII letter by the uppercase version of the letter as per definition of [the algorithm of the Dataset API](http://www.w3.org/TR/html5/dom.html#dom-dataset). Writing a statement like <code>$( "body" ).data( { "my-name": "aValue" } ).data();</code> will return <code>{ myName: "aValue" }</code>.</p>
       <p>Due to the way browsers interact with plugins and external code, the <code>.data()</code> method cannot be used on <code>&lt;object&gt;</code> (unless it's a Flash plugin), <code>&lt;applet&gt;</code> or <code>&lt;embed&gt;</code> elements.</p>
     </longdesc>
     <note id="no-data-on-xml" type="additional"/>
@@ -88,6 +89,7 @@ alert( $( "body" ).data( "foo" ) ); // undefined
 $( "body" ).data( "bar", "foobar" );
 alert( $( "body" ).data( "bar" ) ); // foobar
       </code></pre>
+      <p><strong>jQuery 3</strong> changes the behavior of this method to align it to the <a href="http://www.w3.org/TR/html5/dom.html#dom-dataset">Dataset API specifications</a>. Specifically, jQuery 3 transforms every two-character sequence of "-" (U+002D) followed by a lowercase ASCII letter by the uppercase version of the letter as per definition of [the algorithm of the Dataset API](http://www.w3.org/TR/html5/dom.html#dom-dataset). Writing a statement like <code>$( "body" ).data( { "my-name": "aValue" } ).data();</code> will return <code>{ myName: "aValue" }</code>.</p>
       <h4 id="data-html5">
         <a href="#data-html5">HTML5 data-* Attributes</a>
       </h4>

entries/hidden-selector.xml

@@ -18,6 +18,7 @@
     <p>Elements that are not in a document are not considered to be visible; jQuery does not have a way to know if they will be visible when appended to a document since it depends on the applicable styles.</p>
     <p>During animations to show an element, the element is considered to be visible at the start of the animation.</p>
     <p>How <code>:hidden</code> is determined was changed in jQuery 1.3.2. An element is assumed to be hidden if it or any of its parents consumes no space in the document. CSS visibility isn't taken into account (therefore <code>$( elem ).css( "visibility", "hidden" ).is( ":hidden" ) == false</code>). The <a href="http://blog.jquery.com/2009/02/20/jquery-1-3-2-released/">release notes</a> outline the changes in more detail.</p>
+    <p>jQuery 3 slightly modifies the meaning of <code>:hidden</code> (and therefore of <a href="/visible-selector/"><code>:visible</code></a>). Starting with this version, elements will be considered <code>:hidden</code> if they don't have any layout boxes. For example, <code>br</code> elements and inline elements with no content will not be selected by the <code>:hidden</code> selector.</p>
   </longdesc>
   <note id="jquery-selector-extension" type="additional" data-selector=":hidden"/>
   <note id="hidden-forces-layout" type="additional"/>

entries/jQuery.ajax.xml

@@ -19,7 +19,7 @@
         <desc>The content type sent in the request header that tells the server what kind of response it will accept in return.</desc>
       </property>
       <property default="true" name="async" type="Boolean">
-        <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> with jqXHR (<code>$.Deferred</code>) is deprecated; you must use the success/error/complete callback options instead of the corresponding methods of the jqXHR object such as <code>jqXHR.done()</code> or the deprecated <code>jqXHR.success()</code>.</strong></desc>
+        <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</strong>, the use of <code>async: false</code> with jqXHR (<code>$.Deferred</code>) is deprecated; you must use the success/error/complete callback options instead of the corresponding methods of the jqXHR object such as <code>jqXHR.done()</code>.</desc>
       </property>
       <property name="beforeSend" type="Function">
         <argument name="jqXHR" type="jqXHR"/>
@@ -203,7 +203,7 @@ $.ajax({
     <ul>
       <li>
         <strong>jqXHR.done(function( data, textStatus, jqXHR ) {});</strong>
-        <p>An alternative construct to the success callback option, the <code>.done()</code> method replaces the deprecated <code>jqXHR.success()</code> method. Refer to <code><a href="/deferred.done/">deferred.done()</a></code> for implementation details.</p>
+        <p>An alternative construct to the success callback option, refer to <code><a href="/deferred.done/">deferred.done()</a></code> for implementation details.</p>
       </li>
       <li>
         <strong>jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});</strong>
@@ -222,7 +222,7 @@ $.ajax({
       </li>
     </ul>
     <div class="warning">
-      <p><strong>Deprecation Notice:</strong> The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callbacks are deprecated as of jQuery 1.8. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
+      <p><strong>Deprecation Notice:</strong> The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callbacks are removed as of jQuery 3.0. You can use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
     </div>
     <pre><code>
 // Assign handlers immediately after making the request,

entries/jQuery.get.xml

@@ -75,7 +75,7 @@ jqxhr.always(function() {
 });
     </code></pre>
     <h4>Deprecation Notice</h4>
-    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods introduced in jQuery 1.5 are <strong>deprecated as of jQuery 1.8</strong>. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
+    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods are <strong>removed as of jQuery 3.0</strong>. You can use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
   </longdesc>
   <note id="same-origin-policy" type="additional"/>
   <note id="use-ajaxerror" type="additional" data-title="jQuery.get()"/>

entries/jQuery.getJSON.xml

@@ -87,7 +87,7 @@ jqxhr.complete(function() {
 });
     </code></pre>
     <h4>Deprecation Notice</h4>
-    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods introduced in jQuery 1.5 are <strong>deprecated as of jQuery 1.8</strong>. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
+    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods are <strong>removed as of jQuery 3.0</strong>. You can use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
   </longdesc>
   <note id="same-origin-policy" type="additional"/>
   <note id="same-origin-policy-exceptions" type="additional"/>

entries/jQuery.isNumeric.xml

@@ -10,6 +10,7 @@
   </signature>
   <longdesc>
     <p>The <code>$.isNumeric()</code> method checks whether its argument represents a numeric value. If so, it returns <code>true</code>. Otherwise it returns <code>false</code>. The argument can be of any type.</p>
+    <p>As of jQuery 3.0 <code>$.isNumeric()</code> returns <code>true</code> only if the argument is of type <a href="/Types/#Number"><code>number</code></a>, or if it's of type <code>string</code> and it can be coerced into finite numbers. In all other cases, it returns <code>false</code>.</p>
   </longdesc>
   <example>
     <desc>Sample return values of $.isNumeric with various inputs.</desc>

entries/jQuery.parseHTML.xml

@@ -17,6 +17,7 @@
   <longdesc>
     <p><code>jQuery.parseHTML</code> uses native methods to convert the string to a set of DOM nodes, which can then be inserted into the document. These methods do render all trailing or leading text (even if that's just whitespace). To prevent trailing/leading whitespace from being converted to text nodes you can pass the HTML string through <a href="/jQuery.trim/"><code>jQuery.trim</code></a>.</p>
     <p>By default, the <code>context</code> is the current <code>document</code> if not specified or given as <code>null</code> or <code>undefined</code>. If the HTML was to be used in another document such as an iframe, that frame's document could be used.</p>
+    <p>As of 3.0 the default behavior is changed. If the <code>context</code> is not specified or given as <code>null</code> or <code>undefined</code>, a new <code>document</code> is used. This can potentially improve security because inline events will not execute when the HTML is parsed. Once the parsed HTML is injected into a document it does execute, but this gives tools a chance to traverse the created DOM and remove anything deemed unsafe. This improvement does not apply to internal uses of <code>jQuery.parseHTML</code> as they usually pass in the current <code>document</code>. Therefore, a statement like <code>$( "#log" ).append( $( htmlString ) )</code> is still subject to the injection of malicious code.</p>
 	<h2>Security Considerations</h2>
 	<p>Most jQuery APIs that accept HTML strings will run scripts that are included in the HTML. <code>jQuery.parseHTML</code> does not run script in the parsed HTML unless <code>keepScripts</code> is explicitly <code>true</code>. However, it is still possible in most environments to execute script indirectly, for example via the <code>&lt;img onerror&gt;</code> attribute. The caller should be aware of this and guard against it by cleaning or escaping any untrusted inputs from sources such as the URL or cookies. For future compatibility, callers should not depend on the ability to run <em>any</em> script content when <code>keepScripts</code> is unspecified or <code>false</code>.</p>
   </longdesc>

entries/jQuery.parseJSON.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<entry type="method" name="jQuery.parseJSON">
+<entry type="method" name="jQuery.parseJSON" deprecated="3.0">
   <return type="String"/>
   <return type="Number"/>
   <return type="Object"/>
@@ -26,6 +26,7 @@
     <p>The JSON standard does not permit "control characters" such as a tab or newline. An example like <code>$.parseJSON( '{ "testing":"1\t2\n3" }' )</code> will throw an error in most implementations because the JavaScript parser converts the string's tab and newline escapes into literal tab and newline; doubling the backslashes like <code>"1\\t2\\n3"</code> yields expected results. This problem is often seen when injecting JSON into a JavaScript file from a server-side language such as PHP.</p>
     <p>Where the browser provides a native implementation of <code>JSON.parse</code>, jQuery uses it to parse the string. For details on the JSON format, see <a href="http://json.org/">http://json.org/</a>.</p>
     <p>Prior to jQuery 1.9, <code>$.parseJSON</code> returned <code>null</code> instead of throwing an error if it was passed an empty string, <code>null</code>, or <code>undefined</code>, even though those are not valid JSON.</p>
+    <p>As of jQuery 3.0, <code>$.parseJSON</code> is deprecated. To parse JSON objects, use the native <code>JSON.parse</code> method instead.</p>
   </longdesc>
   <example>
     <desc>Parse a JSON string.</desc>

entries/jQuery.post.xml

@@ -77,7 +77,7 @@ jqxhr.always(function() {
     </code></pre>
 
     <h4>Deprecation Notice</h4>
-    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods introduced in jQuery 1.5 are <strong>deprecated as of jQuery 1.8</strong>. To prepare your code for their eventual removal, use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
+    <p>The <code>jqXHR.success()</code>, <code>jqXHR.error()</code>, and <code>jqXHR.complete()</code> callback methods are <strong>removed as of jQuery 3.0</strong>. You can use <code>jqXHR.done()</code>, <code>jqXHR.fail()</code>, and <code>jqXHR.always()</code> instead.</p>
   </longdesc>
   <note id="same-origin-policy" type="additional"/>
   <note id="use-ajaxerror" type="additional" data-title="jQuery.post()"/>

entries/jQuery.unique.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<entry type="method" name="jQuery.unique" return="Array">
+<entry type="method" name="jQuery.unique" return="Array" deprecated="3.0">
   <title>jQuery.unique()</title>
   <signature>
     <added>1.1.3</added>
@@ -9,6 +9,7 @@
   </signature>
   <desc>Sorts an array of DOM elements, in place, with the duplicates removed. Note that this only works on arrays of DOM elements, not strings or numbers.</desc>
   <longdesc>
+    <p><strong>As of jQuery 3.0, this method is deprecated and just an alias of <code><a href="/jQuery.uniqueSort/">jQuery.uniqueSort()</a></code>. Please use that method instead.</strong></p>
     <p>The <code>$.unique()</code> function searches through an array of objects, sorting the array, and removing any duplicate nodes. A node is considered a duplicate if it is the <em>exact same</em> node as one already in the array; two different nodes with identical attributes are not considered to be duplicates. This function only works on plain JavaScript arrays of DOM elements, and is chiefly used internally by jQuery. You probably will never need to use it.</p>
     <p>As of jQuery 1.4 the results will always be returned in document order.</p>
   </longdesc>

entries/jQuery.uniqueSort.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0"?>
+<entry type="method" name="jQuery.uniqueSort" return="Array">
+  <title>jQuery.uniqueSort()</title>
+  <signature>
+    <added>3.0</added>
+    <argument name="array" type="Array">
+      <desc>The Array of DOM elements.</desc>
+    </argument>
+  </signature>
+  <desc>Sorts an array of DOM elements, in place, with the duplicates removed. Note that this only works on arrays of DOM elements, not strings or numbers.</desc>
+  <longdesc>
+    <p>The <code>$.uniqueSort()</code> function searches through an array of objects, sorting the array, and removing any duplicate nodes. A node is considered a duplicate if it is the <em>exact same</em> node as one already in the array; two different nodes with identical attributes are not considered to be duplicates. This function only works on plain JavaScript arrays of DOM elements, and is chiefly used internally by jQuery. You probably will never need to use it.</p>
+    <p>Prior to jQuery 3.0, this method was called <code><a href="/jQuery.unique/">jQuery.unique()</a></code>.</p>
+    <p>As of jQuery 1.4 the results will always be returned in document order.</p>
+  </longdesc>
+  <example>
+    <desc>Removes any duplicate elements from the array of divs.</desc>
+    <code><![CDATA[
+// unique() must take a native array
+var divs = $( "div" ).get();
+
+// Add 3 elements of class dup too (they are divs)
+divs = divs.concat( $( ".dup" ).get() );
+$( "div:eq(1)" ).text( "Pre-unique there are " + divs.length + " elements." );
+
+divs = jQuery.uniqueSort( divs );
+$( "div:eq(2)" ).text( "Post-unique there are " + divs.length + " elements." )
+  .css( "color", "red" );
+]]></code>
+    <css><![CDATA[
+  div {
+    color: blue;
+  }
+]]></css>
+    <html><![CDATA[
+<div>There are 6 divs in this document.</div>
+<div></div>
+<div class="dup"></div>
+<div class="dup"></div>
+<div class="dup"></div>
+<div></div>
+]]></html>
+  </example>
+  <category slug="utilities"/>
+</entry>