Effects: Clarify that callbacks are per-element

Fixes #803

entries/animate.xml

@@ -32,8 +32,8 @@
     </div>
     <h4 id="duration">Duration</h4>
     <p>Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The default duration is <code>400</code> milliseconds. The strings <code>'fast'</code> and <code>'slow'</code> can be supplied to indicate durations of <code>200</code> and <code>600</code> milliseconds, respectively.</p>
-    <h4 id="complete">Complete Function</h4>
-    <p>If supplied, the <code>complete</code> callback function is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, the callback is executed once per matched element, not once for the animation as a whole.</p>
+    <h4 id="callbacks">Callback Functions</h4>
+    <p>If supplied, the <code>start</code>, <code>step</code>, <code>progress</code>, <code>complete</code>, <code>done</code>, <code>fail</code>, and <code>always</code> callbacks are called on a <em>per-element</em> basis; <code>this</code> is set to the DOM element being animated. If no elements are in the set, no callbacks are called. If multiple elements are animated, the callback is executed once per matched element, not once for the animation as a whole. Use the <code>.promise()</code> method to obtain a promise to which you can attach callbacks that fire once for an animated set of any size, including zero elements.</p>
     <h4 id="basic-usage">Basic Usage</h4>
     <p>To animate any element, such as a simple image:</p>
     <pre><code>

includes/complete-argument.xml

@@ -1,4 +1,4 @@
 <?xml version="1.0"?>
 <argument name="complete" type="Function" optional="true">
-	<desc>A function to call once the animation is complete.</desc>
+	<desc>A function to call once the animation is complete, called once per matched element.</desc>
 </argument>

includes/options-argument.xml

@@ -41,17 +41,17 @@
 		</argument>
 	</property>
 	<property name="complete" type="Function">
-		<desc>A function to call once the animation is complete.</desc>
+		<desc>A function that is called once the animation on an element is complete.</desc>
 		<!-- no parameters -->
 	</property>
 	<property name="start" type="Function" added="1.8">
-		<desc>A function to call when the animation begins.</desc>
+		<desc>A function to call when the animation on an element begins.</desc>
 		<argument name="animation" type="Promise">
 			<desc>An enhanced Promise object with additional properties for the animation</desc>
 		</argument>
 	</property>
 	<property name="done" type="Function" added="1.8">
-		<desc>A function to be called when the animation completes (its Promise object is resolved).</desc>
+		<desc>A function to be called when the animation on an element completes (its Promise object is resolved).</desc>
 		<argument name="animation" type="Promise">
 			<desc>An enhanced Promise object with additional properties for the animation</desc>
 		</argument>
@@ -60,7 +60,7 @@
 		</argument>
 	</property>
 	<property name="fail" type="Function" added="1.8">
-		<desc>A function to be called when the animation fails to complete (its Promise object is rejected).</desc>
+		<desc>A function to be called when the animation on an element fails to complete (its Promise object is rejected).</desc>
 		<argument name="animation" type="Promise">
 			<desc>An enhanced Promise object with additional properties for the animation</desc>
 		</argument>
@@ -69,7 +69,7 @@
 		</argument>
 	</property>
 	<property name="always" type="Function" added="1.8">
-		<desc>A function to be called when the animation completes or stops without completing (its Promise object is either resolved or rejected).</desc>
+		<desc>A function to be called when the animation on an element completes or stops without completing (its Promise object is either resolved or rejected).</desc>
 		<argument name="animation" type="Promise">
 			<desc>An enhanced Promise object with additional properties for the animation</desc>
 		</argument>