All: Added structured types for higer order function parameters

Some function parameters of function type (e.g. handlers, callbacks) was
described with the signature in the name-attribute, eg. <argument
name="function(index, value)" type="Function">. This have been modified
to used nested <argument>-elements to describe the signatures more
consistently.

Changed some argument type from XMLHttpRequest to jsXHR

Some callback functions was indicated to receive XMLHttpRequest rather
than jsXHR.

Fixed spelling and changed 'ajaxOptions' to 'PlainObject'

The ajaxOptions/ajaxSettings options object is not documented as a
seperate type, so now changed to PlainObject. Changed misspelling of
jsXHR to jqXHR.

Changed nargument names to valid identifers to avoid confusion

Argument names with whitespace like "jQuery object" are confusing,
because it might easily be mistaken for two arguments when reading the
signature. Argument names like "-index" are also confusing since they
look like an expression rather than a name. I have renamed the argument
names to be valid javascript identifiers, just like actual argument
names have to be. Also changed argument type "Object" and "PlainObject"
to "JQuery" where the prose documentation indicates that the type is a
jQuery object.

Changed argument name 'jQueryObject' to 'selection'

As per discussion on #jquery-content. Also changed type from 'Object'
to 'jQuery' where prose indicates a jQuery object.

Closes gh-419

entries/add.xml

@@ -21,7 +21,7 @@
   </signature>
   <signature>
     <added>1.3.2</added>
-    <argument name="jQuery object" type="jQuery">
+    <argument name="selection" type="jQuery">
       <desc>An existing jQuery object to add to the set of matched elements.</desc>
     </argument>
   </signature>

entries/addClass.xml

@@ -9,8 +9,11 @@
   </signature>
   <signature>
     <added>1.4</added>
-    <argument name="function(index, currentClass)" type="Function">
+    <argument name="function" type="Function">
       <desc>A function returning one or more space-separated class names to be added to the existing class name(s). Receives the index position of the element in the set and the existing class name(s) as arguments. Within the function, <code>this</code> refers to the current element in the set.</desc>
+      <argument name="index" type="Integer" />
+      <argument name="currentClassName" type="String" />
+      <return type="String"/>
     </argument>
   </signature>
   <desc>Adds the specified class(es) to each of the set of matched elements.</desc>

entries/after.xml

@@ -20,8 +20,15 @@
   </signature>
   <signature>
     <added>1.4</added>
-    <argument name="function(index)" type="Function">
+    <argument name="function" type="Function">
       <desc>A function that returns an HTML string, DOM element(s), or jQuery object to insert after each element in the set of matched elements. Receives the index position of the element in the set as an argument. Within the function, <code>this</code> refers to the current element in the set.</desc>
+      <argument name="index" type="Integer" />
+      <argument name="html" type="String" />
+      <return>
+        <type name="htmlString"/>
+        <type name="Element"/>
+        <type name="jQuery"/>        
+      </return>
     </argument>
   </signature>
   <desc>Insert content, specified by the parameter, after each element in the set of matched elements.</desc>

entries/ajaxComplete.xml

@@ -3,7 +3,10 @@
   <title>.ajaxComplete()</title>
   <signature>
     <added>1.0</added>
-    <argument name="handler(event, XMLHttpRequest, ajaxOptions)" type="Function">
+    <argument name="handler" type="Function">      
+      <argument name="event" type="Event" />
+      <argument name="jqXHR" type="jqXHR" />
+      <argument name="ajaxOptions" type="PlainObject" />
       <desc>The function to be invoked.</desc>
     </argument>
   </signature>

entries/ajaxError.xml

@@ -3,8 +3,12 @@
   <title>.ajaxError()</title>
   <signature>
     <added>1.0</added>
-    <argument name="handler(event, jqXHR, ajaxSettings, thrownError)" type="Function">
+    <argument name="handler" type="Function">
       <desc>The function to be invoked.</desc>
+      <argument name="event" type="Event" />
+      <argument name="jqXHR" type="jqXHR" />
+      <argument name="ajaxSettings" type="PlainObject" />      
+      <argument name="thrownError" type="String" />   
     </argument>
   </signature>
   <desc>Register a handler to be called when Ajax requests complete with an error. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>

entries/ajaxSend.xml

@@ -3,8 +3,11 @@
   <title>.ajaxSend()</title>
   <signature>
     <added>1.0</added>
-    <argument name="handler(event, jqXHR, ajaxOptions)" type="Function">
+    <argument name="handler" type="Function">
       <desc>The function to be invoked.</desc>
+      <argument name="event" type="Event" />
+      <argument name="jqXHR" type="jqXHR" />
+      <argument name="ajaxOptions" type="PlainObject" />
     </argument>
   </signature>
   <desc>Attach a function to be executed before an Ajax request is sent. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>

entries/ajaxStart.xml

@@ -3,7 +3,7 @@
   <title>.ajaxStart()</title>
   <signature>
     <added>1.0</added>
-    <argument name="handler()" type="Function">
+    <argument name="handler" type="Function">
       <desc>The function to be invoked.</desc>
     </argument>
   </signature>

entries/ajaxStop.xml

@@ -4,7 +4,7 @@
   <desc>Register a handler to be called when all Ajax requests have completed. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>
   <signature>
     <added>1.0</added>
-    <argument name="handler()" type="Function">
+    <argument name="handler" type="Function">
       <desc>The function to be invoked.</desc>
     </argument>
   </signature>

entries/ajaxSuccess.xml

@@ -3,8 +3,12 @@
   <title>.ajaxSuccess()</title>
   <signature>
     <added>1.0</added>
-    <argument name="handler(event, XMLHttpRequest, ajaxOptions)" type="Function">
+    <argument name="handler" type="Function">
       <desc>The function to be invoked.</desc>
+      <argument name="event" type="Event" />
+      <argument name="jqXHR" type="jqXHR" />
+      <argument name="ajaxOptions" type="PlainObject" />     
+      <argument name="data" type="PlainObject" />  
     </argument>
   </signature>
   <desc>Attach a function to be executed whenever an Ajax request completes successfully. This is an <a href="/Ajax_Events/">Ajax Event</a>.</desc>

entries/append.xml

@@ -20,8 +20,15 @@
   </signature>
   <signature>
     <added>1.4</added>
-    <argument name="function(index, html)" type="Function">
+    <argument name="function" type="Function">
       <desc>A function that returns an HTML string, DOM element(s), or jQuery object to insert at the end of each element in the set of matched elements. Receives the index position of the element in the set and the old HTML value of the element as arguments. Within the function, <code>this</code> refers to the current element in the set.</desc>
+      <argument name="index" type="Integer" />
+      <argument name="html" type="String" />
+      <return>
+        <type name="htmlString"/>
+        <type name="Element"/>
+        <type name="jQuery"/>        
+      </return>
     </argument>
   </signature>
   <desc>Insert content, specified by the parameter, to the end of each element in the set of matched elements.</desc>

entries/attr.xml

@@ -164,8 +164,14 @@ The title of the emphasis is:<div></div>
       <argument name="attributeName" type="String">
         <desc>The name of the attribute to set.</desc>
       </argument>
-      <argument name="function(index, attr)" type="Function">
+      <argument name="function" type="Function">
         <desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old attribute value as arguments.</desc>
+        <argument name="index" type="Integer" />
+        <argument name="attr" type="String" />
+        <return>
+          <type name="String"/>
+          <type name="Number"/>          
+        </return>
       </argument>
     </signature>
     <desc>Set one or more attributes for the set of matched elements.</desc>

entries/before.xml

@@ -21,6 +21,13 @@
   <signature>
     <added>1.4</added>
     <argument name="function" type="Function">
+      <argument name="index" type="Integer" />
+      <argument name="html" type="String" />
+      <return>
+        <type name="htmlString"/>
+        <type name="Element"/>
+        <type name="jQuery"/>        
+      </return>      
       <desc>A function that returns an HTML string, DOM element(s), or jQuery object to insert before each element in the set of matched elements. Receives the index position of the element in the set as an argument. Within the function, <code>this</code> refers to the current element in the set.
       </desc>
     </argument>

entries/bind.xml

@@ -9,8 +9,9 @@
     <argument name="eventData" type="Object" optional="true">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>

entries/blur.xml

@@ -4,17 +4,19 @@
   <desc>Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.</desc>
   <signature>
     <added>1.0</added>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>
     <added>1.4.3</added>
     <argument name="eventData" type="Object" optional="true">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>

entries/change.xml

@@ -4,17 +4,19 @@
   <desc>Bind an event handler to the "change" JavaScript event, or trigger that event on an element.</desc>
   <signature>
     <added>1.0</added>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>
     <added>1.4.3</added>
     <argument name="eventData" type="Object" optional="true">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>

entries/click.xml

@@ -4,17 +4,19 @@
   <desc>Bind an event handler to the "click" JavaScript event, or trigger that event on an element.</desc>
   <signature>
     <added>1.0</added>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>
     <added>1.4.3</added>
     <argument name="eventData" type="Object" optional="true">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>

entries/closest.xml

@@ -19,7 +19,7 @@
     </signature>
     <signature>
       <added>1.6</added>
-      <argument name="jQuery object" type="jQuery">
+      <argument name="selection" type="jQuery">
         <desc>A jQuery object to match elements against.</desc>
       </argument>
     </signature>

entries/css.xml

@@ -123,8 +123,14 @@ $( "div" ).click(function() {
       <argument name="propertyName" type="String">
         <desc>A CSS property name.</desc>
       </argument>
-      <argument name="function(index, value)" type="Function">
+      <argument name="function" type="Function">
         <desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old value as arguments.</desc>
+        <argument name="index" type="Integer" />
+        <argument name="value" type="String" />
+        <return>  
+          <type name="String"/>
+          <type name="Number"/>
+        </return>
       </argument>
     </signature>
     <signature>

entries/dblclick.xml

@@ -4,17 +4,19 @@
   <desc>Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element.</desc>
   <signature>
     <added>1.0</added>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>
     <added>1.4.3</added>
     <argument name="eventData" type="Object" optional="true">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>

entries/delegate.xml

@@ -10,8 +10,9 @@
     <argument name="eventType" type="String">
       <desc>A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute at the time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>
@@ -25,8 +26,9 @@
     <argument name="eventData" type="Object">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute at the time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>

entries/each.xml

@@ -3,8 +3,10 @@
   <title>.each()</title>
   <signature>
     <added>1.0</added>
-    <argument name="function(index, Element)" type="Function">
+    <argument name="function" type="Function">
       <desc>A function to execute for each matched element.</desc>
+      <argument name="index" type="Integer" />
+      <argument name="element" type="Element" />      
     </argument>
   </signature>
   <desc>Iterate over a jQuery object, executing a function for each matched element. </desc>

entries/eq-selector.xml

@@ -11,7 +11,7 @@
   <signature>
     <sample>:eq(-index)</sample>
     <added>1.8</added>
-    <argument name="-index" type="Integer">
+    <argument name="indexFromEnd" type="Integer">
       <desc>Zero-based index of the element to match, counting backwards from the last element. </desc>
     </argument>
   </signature>

entries/eq.xml

@@ -9,7 +9,7 @@
   </signature>
   <signature>
     <added>1.4</added>
-    <argument name="-index" type="Integer">
+    <argument name="indexFromEnd" type="Integer">
       <desc>An integer indicating the position of the element, counting backwards from the last element in the set. </desc>
     </argument>
   </signature>

entries/error.xml

@@ -4,17 +4,19 @@
   <desc>Bind an event handler to the "error" JavaScript event.</desc>
   <signature>
     <added>1.0</added>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute when the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <signature>
     <added>1.4.3</added>
     <argument name="eventData" type="Object" optional="true">
       <desc>An object containing data that will be passed to the event handler.</desc>
     </argument>
-    <argument name="handler(eventObject)" type="Function">
+    <argument name="handler" type="Function">
       <desc>A function to execute each time the event is triggered.</desc>
+      <argument name="eventObject" type="Event" />
     </argument>
   </signature>
   <longdesc>

entries/filter.xml

@@ -9,8 +9,11 @@
   </signature>
   <signature>
     <added>1.0</added>
-    <argument name="function(index)" type="Function">
+    <argument name="function" type="Function">
       <desc>A function used as a test for each element in the set. <code>this</code> is the current DOM element.</desc>
+      <argument name="index" type="Integer" />
+      <argument name="element" type="Element" />
+      <return type="Boolean" />
     </argument>
   </signature>
   <signature>
@@ -21,7 +24,7 @@
   </signature>
   <signature>
     <added>1.4</added>
-    <argument name="jQuery object" type="Object">
+    <argument name="selection" type="jQuery">
       <desc>An existing jQuery object to match the current set of elements against.</desc>
     </argument>
   </signature>

entries/find.xml

@@ -9,7 +9,7 @@
   </signature>
   <signature>
     <added>1.6</added>
-    <argument name="jQuery object" type="Object">
+    <argument name="selection" type="jQuery">
       <desc>A jQuery object to match elements against.</desc>
     </argument>
   </signature>