Add examples for methods. Partial fix for #64

Author: jzaefferer

entries/autocomplete.xml

@@ -147,7 +147,7 @@
 		<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
-		<method name="search">
+		<method name="search" example-params='""'>
 			<desc>Triggers a <a href="#event-search"><code>search</code></a> event and invokes the data source if the event is not canceled. Can be used by a selectbox-like button to open the suggestions when clicked. When invoked with no parameters, the current input's value is used. Can be called with an empty string and <code>minLength: 0</code> to display all items.</desc>
 			<argument name="value" type="String" optional="true">
 				<desc></desc>

entries/datepicker.xml

@@ -253,7 +253,7 @@
 	</options>
 	<methods>
 		<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
-		<method name="dialog">
+		<method name="dialog" example-params='"10/12/2012"'>
 			<desc>Opens the datepicker in a dialog box.</desc>
 			<argument name="date">
 				<desc>The initial date.</desc>
@@ -270,7 +270,7 @@
 				<desc>The position of the top/left of the dialog as <code>[x, y]</code> or a <code>MouseEvent</code> that contains the coordinates. If not specified the dialog is centered on the screen.</desc>
 			</argument>
 		</method>
-		<method name="isDisabled" return="Boolean">
+		<method name="isDisabled" return="Boolean" example-return-var="isDisabled">
 			<desc>Determine whether a date picker has been disabled.</desc>
 		</method>
 		<method name="hide">
@@ -282,13 +282,15 @@
 		<method name="refresh">
 			<desc>Redraw the date picker, after having made some external modifications.</desc>
 		</method>
-		<method name="getDate" return="Date">
+		<method name="getDate" return="Date" example-return-var="currentDate">
 			<desc>Returns the current date for the datepicker or <code>null</code> if no date has been selected.</desc>
 		</method>
-		<method name="setDate">
+		<method name="setDate" example-params='"10/12/2012"'>
 			<desc>Sets the date for the datepicker. The new date may be a <code>Date</code> object or a string in the current <a href="#option-dateFormat">date format</a> (e.g., <code>"01/26/2009"</code>), a number of days from today (e.g., <code>+7</code>) or a string of values and periods (<code>"y"</code> for years, <code>"m"</code> for months, <code>"w"</code> for weeks, <code>"d"</code> for days, e.g., <code>"+1m +7d"</code>), or <code>null</code> to clear the selected date.</desc>
-			<argument name="date" type="Date">
+			<argument name="date">
 				<desc>The new date.</desc>
+				<type name="String"/>
+				<type name="Date"/>
 			</argument>
 		</method>
 		<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

entries/dialog.xml

@@ -256,7 +256,7 @@
 		<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
-		<method name="isOpen" return="Boolean">
+		<method name="isOpen" return="Boolean" example-return-var="isOpen">
 			<desc>Whether the dialog is currently open.</desc>
 		</method>
 		<method name="moveToTop">

entries/menu.xml

@@ -92,7 +92,7 @@
 				<desc>What triggered the menu to collapse.</desc>
 			</argument>
 		</method>
-		<method name="collapseAll">
+		<method name="collapseAll" example-params='null, true'>
 			<desc>
 				Closes all open sub-menus.
 			</desc>
@@ -110,27 +110,27 @@
 			<desc>
 				Opens the sub-menu below the currently active item, if one exists.
 			</desc>
-			<argument name="event" type="Event" optional="false">
+			<argument name="event" type="Event" optional="true">
 				<desc>What triggered the menu to expand.</desc>
 			</argument>
 		</method>
-		<method name="focus">
+		<method name="focus" example-params='null, menu.find( ".ui-menu-item:last" )'>
 			<desc>
 				Activates a particular menu item, begins opening any sub-menu if present and triggers the menu's <a href="#event-focus"><code>focus</code></a> event.
 			</desc>
-			<argument name="event" type="Event" optional="false">
+			<argument name="event" type="Event" optional="true">
 				<desc>What triggered the menu item to gain focus.</desc>
 			</argument>
-			<argument name="item" type="jQuery" optional="false">
+			<argument name="item" type="jQuery">
 				<desc>The menu item to focus/activate.</desc>
 			</argument>
 		</method>
-		<method name="isFirstItem">
+		<method name="isFirstItem" example-return-var="firstItem">
 			<desc>
 				Returns a boolean value stating whether or not the currently active item is the first item in the menu.
 			</desc>
 		</method>
-		<method name="isLastItem">
+		<method name="isLastItem" example-return-var="lastItem">
 			<desc>
 				Returns a boolean value stating whether or not the currently active item is the last item in the menu.
 			</desc>

entries/progressbar.xml

@@ -39,10 +39,10 @@
 		<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<method name="value">
 			<desc>Gets or sets the current value of the progressbar.</desc>
-			<signature return="Number">
+			<signature return="Number" example-return-var="progressSoFar">
 				<desc>Gets the current value of the progressbar.</desc>
 			</signature>
-			<signature>
+			<signature example-params='50'>
 				<desc>Sets the current value of the progressbar.</desc>
 				<argument name="value" type="Number">
 					<desc>The value to set.</desc>

entries/slider.xml

@@ -112,10 +112,10 @@
 		<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
 		<method name="value">
 			<desc>Get or set the value of the slider.</desc>
-			<signature return="Number">
+			<signature return="Number" example-return-var="selection">
 				<desc>Get the value of the slider.</desc>
 			</signature>
-			<signature>
+			<signature example-params="55">
 				<desc>Set the value of the slider.</desc>
 				<argument name="value" type="Number">
 					<desc>The value to set.</desc>
@@ -124,16 +124,16 @@
 		</method>
 		<method name="values">
 			<desc>Get or set the handle value(s).</desc>
-			<signature return="Array">
+			<signature return="Array" example-return-var="values">
 				<desc>Get the value for all handles.</desc>
 			</signature>
-			<signature return="Number">
+			<signature return="Number" example-return-var="value" example-params="0">
 				<desc>Get the value for the specified handle.</desc>
 				<argument name="index" type="Integer">
 					<desc>The zero-based index of the handle.</desc>
 				</argument>
 			</signature>
-			<signature>
+			<signature example-params="0, 55">
 				<desc>Set the value for the specified handle.</desc>
 				<argument name="index" type="Integer">
 					<desc>The zero-based index of the handle.</desc>
@@ -142,7 +142,7 @@
 					<desc>The value to set.</desc>
 				</argument>
 			</signature>
-			<signature>
+			<signature example-params="[ 55, 105 ]">
 				<desc>Set the value for all handles.</desc>
 				<argument name="values" type="Array">
 					<desc>The values to set.</desc>

entries/sortable.xml

@@ -432,7 +432,7 @@
 		<method name="refreshPositions">
 			<desc>Refresh the cached positions of the sortable items. Calling this method refreshes the cached item positions of all sortables.</desc>
 		</method>
-		<method name="serialize">
+		<method name="serialize" return="String" example-return-var="sorted" example-params='{ key: "sort" }'>
 			<desc>
 				<p>Serializes the sortable's item <code>id</code>s into a form/ajax submittable string. Calling this method produces a hash that can be appended to any url to easily submit a new item order back to the server.</p>
 
@@ -442,18 +442,18 @@
 			</desc>
 			<argument name="options" type="Object">
 				<desc>Options to customize the serialization.</desc>
-				<property name="key" type="String">
+				<property name="key" type="String" default="the part of the attribute in front of the separator">
 					<desc>Replaces <code>part1[]</code> with the specified value.</desc>
 				</property>
-				<property name="attribute" type="String">
+				<property name="attribute" type="String" default='"id"'>
 					<desc>The name of the attribute to use for the values.</desc>
 				</property>
-				<property name="expression" type="RegExp">
+				<property name="expression" type="RegExp" default="/(.+)[-=_](.+)/">
 					<desc>A regular expression used to split the attribute value into key and value parts.</desc>
 				</property>
 			</argument>
 		</method>
-		<method name="toArray">
+		<method name="toArray" return="Array" example-return-var="sortedIDs">
 			<desc>Serializes the sortable's item id's into an array of string.</desc>
 		</method>
 		<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

entries/spinner.xml

@@ -90,7 +90,7 @@
 				<desc>Number of pages to decrement, defaults to 1.</desc>
 			</argument>
 		</method>
-		<method name="pageUp">
+		<method name="pageUp" example-params='10'>
 			<desc>
 				Increments the value by the specified number of pages, as defined by the <a href="#option-page"><code>page</code></a> option. Without the parameter, a single page is incremented.
 			</desc>
@@ -107,7 +107,7 @@
 				<desc>Number of steps to decrement, defaults to 1.</desc>
 			</argument>
 		</method>
-		<method name="stepUp">
+		<method name="stepUp" example-params='5'>
 			<desc>
 				Increments the value by the specified number of steps. Without the parameter, a single step is incremented.
 				<p>If the resulting value is above the max, below the min, or reuslts in a step mismatch, the value will be adjusted to the closest valid value.</p>
@@ -120,10 +120,10 @@
 			<desc>
 				Gets or sets the current value as a number.
 			</desc>
-			<signature return="Number">
+			<signature return="Number" example-return-var="value">
 				<desc>Gets the current value as a number. The value is parsed based on the <a href="#option-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options.</desc>
 			</signature>
-			<signature>
+			<signature example-params='50'>
 				<argument name="value">
 					<desc>The value to set. If passed as a string, the value is parsed based on the <a href="#option-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options.</desc>
 					<type name="Number"/>

entries/tabs.xml

@@ -156,7 +156,7 @@
 			<signature>
 				<desc>Disables all tabs.</desc>
 			</signature>
-			<signature>
+			<signature example-params='1'>
 				<desc>
 					Disables a tab. The selected tab cannot be disabled. To disable more than one tab at once, set the <a href="#option-disabled"><code>disabled</code></a> option: <code>$( "#tabs" ).tabs( "option", "disabled", [ 1, 2, 3 ] )</code>.
 				</desc>
@@ -175,7 +175,7 @@
 			<signature>
 				<desc>Enables all tabs.</desc>
 			</signature>
-			<signature>
+			<signature example-params='1'>
 				<desc>Enables a tab. To enable more than one tab at once reset the disabled property like: <code>$( "#example" ).tabs( "option", "disabled", [] );</code>.</desc>
 				<argument name="index">
 					<desc>Which tab to enable.</desc>
@@ -188,7 +188,7 @@
 				</argument>
 			</signature>
 		</method>
-		<method name="load">
+		<method name="load" example-params='1'>
 			<desc>Loads the panel content of a remote tab.</desc>
 			<argument name="index">
 				<desc>Which tab to load.</desc>

includes/widget-method-option.xml

@@ -3,16 +3,16 @@
 	<desc>
 		Sets one or more options for the <placeholder name="name"/>.
 	</desc>
-	<signature return="Object">
+	<signature return="Object" example-return-var="isDisabled" example-params='"disabled"'>
 		<desc>Gets the value currently associated with the specified <code>optionName</code>.</desc>
 		<argument name="optionName" type="String">
 			<desc>The name of the option to get.</desc>
 		</argument>
 	</signature>
-	<signature return="PlainObject">
+	<signature return="PlainObject" example-return-var="options">
 		<desc>Gets an object containing key/value pairs representing the current <placeholder name="name"/> options hash.</desc>
 	</signature>
-	<signature>
+	<signature example-params='"disabled", true'>
 		<desc>Sets the value of the <placeholder name="name"/> option associated with the specified <code>optionName</code>.</desc>
 		<argument name="optionName" type="String">
 			<desc>The name of the option to set.</desc>
@@ -21,7 +21,7 @@
 			<desc>A value to set for the option.</desc>
 		</argument>
 	</signature>
-	<signature>
+	<signature example-params="{ disabled: true }">
 		<desc>Sets one or more options for the <placeholder name="name"/>.</desc>
 		<argument name="options" type="Object">
 			<desc>A map of option-value pairs to set.</desc>

includes/widget-method-widget.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<method name="widget" return="jQuery">
+<method name="widget" return="jQuery" example-return-var="widget">
 	<desc>
 		Returns a <code>jQuery</code> object containing the <placeholder name="widget-element"/>.
 	</desc>