clarify docs for onmutation

pkg/polymer/lib/src/instance.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 polymer;
 
 /**
  * Use this annotation to publish a field as an attribute. For example:
  *
  *     class MyPlaybackElement extends PolymerElement {
@@ skipping 246 matching lines @@
     }
   }
 
   void attributeChanged(String name, String oldValue) {
     if (name != 'class' && name != 'style') {
       attributeToProperty(name, attributes[name]);
     }
   }
 
   // TODO(jmesserly): use stream or future here?
+  /**
+   * Run the `listener` callback *once*
+   * when `node` changes, or when its children or subtree changes.
+   * 
+   *
+   * See [MutationObserver] if you want to listen to a stream of
+   * changes.
+   */
   void onMutation(Node node, void listener(MutationObserver obs)) {
     new MutationObserver((records, MutationObserver observer) {
       listener(observer);
       observer.disconnect();
     })..observe(node, childList: true, subtree: true);
   }
 
   void copyInstanceAttributes() {
     _declaration._instanceAttributes.forEach((name, value) {
       attributes.putIfAbsent(name, () => value);
@@ skipping 644 matching lines @@
 }
 
 final Logger _observeLog = new Logger('polymer.observe');
 final Logger _eventsLog = new Logger('polymer.events');
 final Logger _unbindLog = new Logger('polymer.unbind');
 final Logger _bindLog = new Logger('polymer.bind');
 
 final Expando _shadowHost = new Expando<Element>();
 
 final Expando _eventHandledTable = new Expando<Set<Node>>();