Docs and tests for animation methods.

lib/OpenLayers/Util.js

@@ -1697,8 +1697,16 @@ OpenLayers.Util.getFormattedLonLat = function(coordinate, axis, dmsOption) {
     return str;
 };
 
-OpenLayers.Util.requestAnimationFrame = (function() {
-    return window.requestAnimationFrame ||
+/**
+ * Function: requestAnimationFrame
+ * Schedule a function to be called at the next available animation frame.
+ *     Uses the native method where available.  Where requestAnimationFrame is
+ *     not available, setTimeout will be called with a 16ms delay.
+ *
+ * Parameters:
+ * callback - {Function} The function to be called at the next animation frame.
+ * element - {DOMElement} Optional element that visually bounds the animation.
+ */
 OpenLayers.Util.requestAnimationFrame = (function(window) {
     var request = window.requestAnimationFrame ||
         window.webkitRequestAnimationFrame ||
@@ -1720,6 +1728,21 @@ OpenLayers.Util.requestAnimationFrame = (function(window) {
     var loops = {};
     var request = OpenLayers.Util.requestAnimationFrame;
     
+    /**
+     * Function: startAnimation
+     * Executes a method with <requestAnimationFrame> in series for some 
+     *     duration.
+     *
+     * Parameters:
+     * callback - {Function} The function to be called at the next animation frame.
+     * duration - {Number} Optional duration for the loop.  If not provided, the
+     *     animation loop will execute indefinitely.
+     * element - {DOMElement} Optional element that visually bounds the animation.
+     *
+     * Returns:
+     * {Number} Identifier for the animation loop.  Used to stop animations with
+     *     <stopAnimation>.
+     */
     OpenLayers.Util.startAnimation = function(callback, duration, element) {
         duration = duration > 0 ? duration : Number.POSITIVE_INFINITY;
         var id = ++counter;
@@ -1738,6 +1761,13 @@ OpenLayers.Util.requestAnimationFrame = (function(window) {
         return id;
     }
     
+    /**
+     * Function: stopAnimation
+     * Terminates an animation loop started with <startAnimation>.
+     *
+     * Parameters:
+     * {Number} Identifier returned from <startAnimation>.
+     */
     OpenLayers.Util.stopAnimation = function(id) {
         delete loops[id];
     }