Remove recommendation that removeData() is the same as data("key", undefined). Closes #542.

Author: mattlunn

entries/data.xml

@@ -8,8 +8,8 @@
       <argument name="key" type="String">
         <desc>A string naming the piece of data to set.</desc>
       </argument>
-      <argument name="value" type="Object">
-        <desc>The new data value; it can be any Javascript type including Array or Object.</desc>
+      <argument name="value" type="Anything">
+        <desc>The new data value; this can be any Javascript type except <code>undefined</code>.</desc>
       </argument>
     </signature>
     <signature>
@@ -30,10 +30,11 @@ $( "body" ).data( "foo" ); // 52
 $( "body" ).data(); // { foo: 52, bar: { myType: "test", count: 40 }, baz: [ 1, 2, 3 ] }
       </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. jQuery itself uses the <code>.data()</code> method to save information under the names 'events' and 'handle', and also reserves any data name starting with an underscore ('_') for internal use.</p>
-      <p>Prior to jQuery 1.4.3 (starting in jQuery 1.4) the .data() 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>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>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"/>
+    <note id="data-doesnt-accept-undefined" type="additional" data-title=".data" data-parameters="&quot;name&quot;"/>
     <example>
       <desc>Store then retrieve a value from the div element.</desc>
       <code><![CDATA[

entries/jQuery.data.xml

@@ -11,8 +11,8 @@
       <argument name="key" type="String">
         <desc>A string naming the piece of data to set.</desc>
       </argument>
-      <argument name="value" type="Object">
-        <desc>The new data value.</desc>
+      <argument name="value" type="Anything">
+        <desc>The new data value; this can be any Javascript type except <code>undefined</code>.</desc>
       </argument>
     </signature>
     <desc>Store arbitrary data associated with the specified element. Returns the value that was set.</desc>
@@ -23,8 +23,9 @@
 jQuery.data( document.body, "foo", 52 );
 jQuery.data( document.body, "bar", "test" );
       </code></pre>
-      <p><em>Note:</em> this method currently does not provide cross-platform support for setting data on XML documents, as Internet Explorer does not allow data to be attached via expando properties.</p>
     </longdesc>
+    <note id="no-data-on-xml" type="additional"/>
+    <note id="data-doesnt-accept-undefined" type="additional" data-title="jQuery.data" data-parameters="el, &quot;name&quot;"/>
     <example>
       <desc>Store then retrieve a value from the div element.</desc>
       <code><![CDATA[

entries/removeData.xml

@@ -17,10 +17,13 @@
   </signature>
   <desc>Remove a previously-stored piece of data.</desc>
   <longdesc>
-    <p>The <code>.removeData()</code> method allows us to remove values that were previously set using <code>.data()</code>. When called with the name of a key, <code>.removeData()</code> deletes that particular value; when called with no arguments, all values are removed. Removing data from jQuery's internal <code>.data()</code> cache does not affect any HTML5 <code>data-</code> attributes in a document; use <code>.removeAttr()</code> to remove those.</p>
-    <p>When using <code>.removeData("name")</code>, jQuery will attempt to locate a <code>data-</code> attribute on the element if no property by that name is in the internal data cache. To avoid a re-query of the <code>data-</code> attribute, set the name to a value of either <code>null</code> or <code>undefined</code> (e.g. <code>.data("name", undefined)</code>) rather than using <code>.removeData()</code>.</p>
+    <p>The <code>.removeData()</code> method allows us to remove values that were previously set using <code>.data()</code>. When called with the name of a key, <code>.removeData()</code> deletes that particular value. When called with no arguments, <code>.removeData()</code> removes all values.</p>
+    <p>
+      Note that <code>.removeData()</code> will only remove data from jQuery's internal <code>.data()</code> cache, and any corresponding <code>data-</code> attributes on the element will not be removed. A later call to <code>data()</code>
+      will therefore re-retrieve the value from the <code>data-</code> attribute. To prevent this, use <code>.removeAttr()</code> alongside <code>.removeData()</code> to remove the <code>data-</code> attribute as well. Prior to jQuery 1.4.3,
+      as <code>data()</code> did not use <code>data-</code> attributes, this was not an issue.
+    </p>
     <p><strong>As of jQuery 1.7</strong>, when called with an array of keys or a string of space-separated keys, <code>.removeData()</code> deletes the value of each key in that array or string.</p>
-    <p><strong>As of jQuery 1.4.3</strong>, calling <code>.removeData()</code> will cause the value of the property being removed to revert to the value of the data attribute of the same name in the DOM, rather than being set to <code>undefined</code>.</p>
   </longdesc>
   <example>
     <desc>Set a data store for 2 names then remove one of them.</desc>

notes.xsl

@@ -1,15 +1,15 @@
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 <xsl:template name="note">
 	<xsl:choose>
+		<xsl:when test="@id = 'data-doesnt-accept-undefined'">
+			<code>undefined</code> is not recognised as a data value. Calls such as <code><xsl:value-of select="@data-title" />( <xsl:value-of select="@data-parameters" />, undefined )</code> will return the corresponding data for "name", and is therefore the same as <code><xsl:value-of select="@data-title" />( <xsl:value-of select="@data-parameters" /> )</code>.
+		</xsl:when>
 		<xsl:when test="@id = 'dimensions-number'">
 			The numbers returned by dimensions-related APIs, including <code><xsl:value-of select="@data-title"/></code>, may be fractional in some cases. Code should not assume it is an integer. Also, dimensions may be incorrect when the page is zoomed by the user; browsers do not expose an API to detect this condition.
 		</xsl:when>
 		<xsl:when test="@id = 'disconnected-manipulation'">
 			Prior to jQuery 1.9, <code><xsl:value-of select="@data-title"/></code> would attempt to add or change nodes in the current jQuery set if the first node in the set was not connected to a document, and in those cases return a new jQuery set rather than the original set. The method might or might not have returned a new result depending on the number or connectedness of its arguments! As of jQuery 1.9, <code>.after()</code>, <code>.before()</code>, and <code>.replaceWith()</code> always return the original unmodified set. Attempting to use these methods on a node without a parent has no effect—that is, neither the set nor the nodes it contains are changed.
 		</xsl:when>
-		<xsl:when test="@id = 'removes-data'">
-			The <code><xsl:value-of select="@data-title"/></code> method removes all data and event handlers associated with the removed nodes.
-		</xsl:when>
 		<xsl:when test="@id = 'document-order'">
 			Selected elements are in the order of their appearance in the document.
 		</xsl:when>
@@ -34,6 +34,9 @@
 		<xsl:when test="@id = 'propagation-for-live-or-delegate'">
 			Since the <a href="/live/"><code>.live()</code></a> method handles events once they have propagated to the top of the document, it is not possible to stop propagation of live events. Similarly, events handled by <code><a href="/delegate/">.delegate()</a></code> will propagate to the elements to which they are delegated; event handlers bound on any elements below it in the DOM tree will already have been executed by the time the delegated event handler is called. These handlers, therefore, may prevent the delegated handler from triggering by calling <code><a href="/event.stopPropagation/">event.stopPropagation()</a></code> or returning <code>false</code>.
 		</xsl:when>
+		<xsl:when test="@id = 'removes-data'">
+			The <code><xsl:value-of select="@data-title"/></code> method removes all data and event handlers associated with the removed nodes.
+		</xsl:when>
 		<xsl:when test="@id = 'same-origin-policy'">
 			Due to browser security restrictions, most "Ajax" requests are subject to the <a title="Same Origin Policy on Wikipedia" href="http://en.wikipedia.org/wiki/Same_origin_policy">same origin policy</a>; the request can not successfully retrieve data from a different domain, subdomain, port, or protocol.
 		</xsl:when>