Improve documentation for animationFrame.

tools/dom/templates/html/impl/impl_Window.darttemplate

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of $LIBRARYNAME;
 
 $if DART2JS
 $(ANNOTATIONS)class $CLASSNAME$EXTENDS$IMPLEMENTS native "Window,DOMWindow" {
 $else
 $(ANNOTATIONS)class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
@@ skipping 30 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 256 matching lines @@
       return wrapped.returnValue;
     });
 
     return controller.stream;
   }
 
   String getEventType(EventTarget target) {
     return _eventType;
   }
 }