Improve documentation for animationFrame.

sdk/lib/html/dart2js/html_dart2js.dart

 /// The Dart HTML library.
 library dart.dom.html;
 
 import 'dart:async';
 import 'dart:collection';
 import 'dart:_collection-dev' hide Symbol;
 import 'dart:html_common';
 import 'dart:indexed_db';
 import 'dart:isolate';
 import 'dart:json' as json;
@@ skipping 22904 matching lines @@
    * port may be retrieved by any isolate (or JavaScript script)
    * running in this window.
    */
   void registerPort(String name, var port) {
     var serialized = _serialize(port);
     document.documentElement.attributes['dart-port:$name'] =
         json.stringify(serialized);
   }
 
   /**
-   * Returns a Future that completes just before the window is about to repaint
-   * so the user can draw an animation frame
+   * Returns a Future that completes just before the window is about to 
+   * repaint so the user can draw an animation frame.
    *
    * If you need to later cancel this animation, use [requestAnimationFrame]
    * instead.
    *
+   * The [Future] completes to a timestamp that represents a floating
+   * point value of the number of milliseconds that have elapsed since the page 
+   * started to load (which is also the timestamp at this call to 
+   * animationFrame).
+   *
    * Note: The code that runs when the future completes should call
    * [animationFrame] again for the animation to continue.
    */
   Future<num> get animationFrame {
     var completer = new Completer<num>();
     requestAnimationFrame((time) {
       completer.complete(time);
     });
     return completer.future;
   }
@@ skipping 6919 matching lines @@
       _position = nextPosition;
       return true;
     }
     _current = null;
     _position = _array.length;
     return false;
   }
 
   T get current => _current;
 }