Updating MutationObserver.observe documentation.

tools/dom/templates/html/impl/impl_MutationObserver.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;
 
 $(ANNOTATIONS)$(CLASS_MODIFIERS)class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
 $!MEMBERS
   /**
    * Checks to see if the mutation observer API is supported on the current
    * platform.
    */
   static bool get supported {
 $if DARTIUM
     return true;
 $else
     return JS('bool',
         '!!(window.MutationObserver || window.WebKitMutationObserver)');
 $endif
   }
 
+  /**
+   * Observes the target for the specified changes.

[Andrei Mouravski, 2013/10/24 17:35:51]

Maybe "Observes the target node for DOM changes." (Or say mutations.)

+   *

[Andrei Mouravski, 2013/10/24 17:35:51]

"[childList], ... , and [attributeFilter] configure which mutations are
observed.
If [childList] is `true`, then mutations to [target]'s children are observed.
..."

+   * Some requirements for the optional parameters:
+   *
+   * * Either childList, attributes or characterData must be true.

[Andrei Mouravski, 2013/10/24 17:35:51]

"At least one of [childList]... must be `true`."

+   * * If attributeOldValue is true then attributes must also be true.
+   * * If attributeFilter is specified then attributes must be true.

[Andrei Mouravski, 2013/10/24 17:35:51]

"...must also be `true`."

+   * * If characterDataOldValue is true then characterData must be true.

[Andrei Mouravski, 2013/10/24 17:35:51]

"...must also be `true`."

+   */
   void observe(Node target,
                {bool childList,
                 bool attributes,
                 bool characterData,
                 bool subtree,
                 bool attributeOldValue,
                 bool characterDataOldValue,
                 List<String> attributeFilter}) {
 
     // Parse options into map of known type.
@@ skipping 52 matching lines @@
     return JS('MutationObserver',
         'new(window.MutationObserver||window.WebKitMutationObserver||'
         'window.MozMutationObserver)(#)',
         convertDartClosureToJS(_wrapBinaryZone(callback), 2));
   }
 $else
   factory MutationObserver(MutationCallback callback) =>
       new MutationObserver._(_wrapBinaryZone(callback));
 $endif
 }