Update EventStream docs with new capture method on the string.

tools/dom/src/EventStreamProvider.dart

 // Copyright (c) 2013, 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 html;
 
 /**
  * Adapter for exposing DOM events as Dart streams.
  */
 class _EventStream<T extends Event> extends Stream<T> {
@@ skipping 23 matching lines @@
 abstract class ElementStream<T extends Event> implements Stream<T> {
   /**
    * Return a stream that only fires when the particular event fires for
    * elements matching the specified CSS selector.
    *
    * This is the Dart equivalent to jQuery's
    * [delegate](http://api.jquery.com/delegate/).
    */
   Stream<T> matches(String selector);
 
+  /**
+   * Adds a capturing subscription to this stream.
+   *
+   * If the target of the event is a descendant of the element from which this
+   * stream derives then [onData] is called before the event propagates down to
+   * the target. This is the opposite of bubbling behavior, where the event
+   * is first processed for the event target and then bubbles upward.
+   *
+   * ## Other Resources
+   *
+   * * [Event Capture]
+   * (http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow-capture)
+   * from the W3C DOM Events specification.
+   */
   StreamSubscription<T> capture(void onData(T event));
 }
 
 /**
  * Adapter for exposing DOM Element events as streams, while also allowing
  * event delegation.
  */
 class _ElementEventStreamImpl<T extends Event> extends _EventStream<T>
     implements ElementStream<T> {
   _ElementEventStreamImpl(target, eventType, useCapture) :
@@ skipping 257 matching lines @@
   /**
    * Gets a [Stream] for this event type, on the specified target.
    *
    * This will always return a broadcast stream so multiple listeners can be
    * used simultaneously.
    *
    * This may be used to capture DOM events:
    *
    *     Element.keyDownEvent.forTarget(element, useCapture: true).listen(...);
    *
+   *     // Alternate method:
+   *     Element.keyDownEvent.forTarget(element).capture(...);
+   *
    * Or for listening to an event which will bubble through the DOM tree:
    *
    *     MediaElement.pauseEvent.forTarget(document.body).listen(...);
    *
    * See also:
    *
    * [addEventListener](http://docs.webplatform.org/wiki/dom/methods/addEventListener)
    */
   Stream<T> forTarget(EventTarget e, {bool useCapture: false}) =>
     new _EventStream(e, _eventType, useCapture);
 
   /**
    * Gets an [ElementEventStream] for this event type, on the specified element.
    *
    * This will always return a broadcast stream so multiple listeners can be
    * used simultaneously.
    *
    * This may be used to capture DOM events:
    *
    *     Element.keyDownEvent.forElement(element, useCapture: true).listen(...);
    *
+   *     // Alternate method:
+   *     Element.keyDownEvent.forElement(element).capture(...);
+   *
+   * Or for listening to an event which will bubble through the DOM tree:
+   *
+   *     MediaElement.pauseEvent.forElement(document.body).listen(...);
+   *
    * See also:
    *
    * [addEventListener](http://docs.webplatform.org/wiki/dom/methods/addEventListener)
    */
   ElementStream<T> forElement(Element e, {bool useCapture: false}) {
     return new _ElementEventStreamImpl(e, _eventType, useCapture);
   }
 
   /**
    * Gets an [ElementEventStream] for this event type, on the list of elements.
@@ skipping 45 matching lines @@
 
   ElementStream<T> _forElementList(ElementList e,
       {bool useCapture: false}) {
     return new _ElementListEventStreamImpl(e, _eventTypeGetter(e), useCapture);
   }
 
   String getEventType(EventTarget target) {
     return _eventTypeGetter(target);
   }
 }