jQuery.widget: Document that instance can be called on any element to determine whether it is a widget. Fixes jquery#77.

jQuery.widget: More explicit wording to clarify the difference between using :data and instance().

jQuery.widget: Minor updates

Author: tjvantoll

entries/jQuery.widget.xml

@@ -87,17 +87,30 @@
 
 			<h3>Instance</h3>
 
-			<p>The widget's instance can be retrieved from a given element using the <a href="#method-instance">instance method</a>.</p>
+			<p>The widget's instance can be retrieved from a given element using the <a href="#method-instance"><code>instance()</code></a> method.</p>
 
 			<pre><code>
 				$( "#elem" ).progressbar( "instance" );
 			</code></pre>
 
-			<p>The instance is stored using <a href="http://api.jquery.com/jQuery.data/"><code>jQuery.data()</code></a> with the widget's full name as the key. Therefore, you can use the <a href="/data-selector"><code>:data</code></a> selector to determine whether an element has a given widget bound to it.</p>
+			<p>If the <code>instance()</code> method is called on an element that is not associated with the widget, <code>undefined</code> is returned.</p>
+
+			<pre><code>
+				$( "#not-a-progressbar" ).progressbar( "instance" ); // undefined
+			</code></pre>
+
+			<p>The instance is stored using <a href="http://api.jquery.com/jQuery.data/"><code>jQuery.data()</code></a> with the widget's full name as the key. Therefore, the <a href="/data-selector/"><code>:data</code></a> selector can also determine whether an element has a given widget bound to it.</p>
 
 			<pre><code>
 				$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true
-				$( "#elem" ).is( ":data( 'ui-draggable' )" ); //false
+				$( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
+			</code></pre>
+
+			<p>Unlike <code>instance()</code>, <code>:data</code> can be used even if the widget being tested for has not loaded.</p>
+
+			<pre><code>
+				$( "#elem" ).nonExistentWidget( "instance" ); // TypeError
+				$( "#elem" ).is( ":data( 'ui-nonExistentWidget' )" ); // false
 			</code></pre>
 
 			<p>You can also use <code>:data</code> to get a list of all elements that are instances of a given widget.</p>

includes/widget-method-instance.xml

@@ -1,6 +1,8 @@
 <?xml version="1.0"?>
-<method name="instance">
+<method name="instance" return="Object">
 	<desc>
-		Retrieves the <placeholder name="name"/>'s instance object.
+		<p>Retrieves the <placeholder name="name"/>'s instance object. If the element does not have an associated instance, <code>undefined</code> is returned.</p>
+
+		<p>Unlike other widget methods, <code>instance()</code> is safe to call on any element after the <placeholder name="name"/> plugin has loaded.</p>
 	</desc>
 </method>