Add docs.

lib/legacy/polymer.dom.html

@@ -94,8 +94,10 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     /**
      * Returns the root node of this node.  Equivalent to `getRoodNode()`.
      *
-     * @return {Node} Host of the shadow root this element is contained
-     *   within, or else the main `document`.
+     * @return {Node} Top most element in the dom tree in which the node
+     * exists. If the node is connected to a document this is either a
+     * shadowRoot or the document; otherwise, it may be the node
+     * itself or a node or document fragment containing it.
      */
     getOwnerRoot() {
       return this.node.getRootNode();
@@ -103,7 +105,7 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
 
     /**
      * For slot elements, returns the nodes assigned to the slot; otherwise
-     * an empty array.
+     * an empty array. It is equivalent to `<slot>.addignedNodes({flatten:true})`.
      *
      * @return {Array<Node>} Array of assigned nodes
      */
@@ -131,15 +133,15 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     /**
      * Calls `importNode` on the `ownerDocument` for this node.
      *
-     * @param {Node} externalNode Node to import
+     * @param {Node} node Node to import
      * @param {boolean} deep True if the node should be cloned deeply during
      *   import
      * @return {Node} Clone of given node imported to this owner document
      */
-    importNode(externalNode, deep) {
+    importNode(node, deep) {
       let doc = this.node instanceof Document ? this.node :
         this.node.ownerDocument;
-      return doc.importNode(externalNode, deep);
+      return doc.importNode(node, deep);
     }
 
     /**

lib/utils/flattened-nodes-observer.html

@@ -17,8 +17,47 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
     return (node.localName === 'slot');
   }
 
+  /**
+   * Class that listens for changes (additions or removals) to
+   * "flattened nodes" on a given `node`. The list of flattened nodes consists
+   * of a node's children and, for any children that are <slot> elements,
+   * the expanded flattened list of `assignedNodes`.
+   * For example, if the observed node has children `<a></a><slot></slot><b></b>`
+   * and the `<slot>` has one `<div>` assigned to it, then the flattened
+   * nodes list is `<a></a><div></div><b></b>`. If the `<slot>` has other
+   * `<slot>` elements assigned to it, these are flattened as well.
+   *
+   * The provided `callback` is called whenever any change to this list
+   * of flattened nodes occurs, where an addition or removal of a node is
+   * considered a change. The `callback` is called with one argument, an object
+   * containing an array of any `addedNodes` and `removedNodes`.
+   *
+   * Note: the callback is called asynchronous to any changes
+   * at a microtask checkpoint. This is because observation is performed using
+   * `MutationObserver` and the `<slot> element's `slotchange` event which
+   * are asynchronous.
+   *
+   * @memberof Polymer
+   * @param {Node} target Node on which to listen for changes.
+   * @param {Function} callback Function called when there are additions
+   * or removals from the target's list of flattened nodes.
+   * @summary Class that listens for changes (additions or removals) to
+   * "flattened nodes" on a given `node`.
+   */
   class FlattenedNodesObserver {
 
+    /**
+     * Returns the list of flattened nodes for the given `node`.
+     * This list consists of a node's children and, for any children
+     * that are <slot> elements, the expanded flattened list of `assignedNodes`.
+     * For example, if the observed node has children `<a></a><slot></slot><b></b>`
+     * and the `<slot>` has one `<div>` assigned to it, then the flattened
+     * nodes list is `<a></a><div></div><b></b>`. If the `<slot>` has other
+     * `<slot>` elements assigned to it, these are flattened as well.
+     *
+     * @param {Node} node The node for which to return the list of flattened nodes.
+     * @returns {Array} The list of flattened nodes for the given `node`.
+    */
     static getFlattenedNodes(node) {
       if (isSlot(node)) {
         return node.assignedNodes({flatten: true});
@@ -47,11 +86,16 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       this._boundSchedule = () => {
         this._schedule();
       }
-      this._connect();
+      this.connect();
       this._schedule();
     }
 
-    _connect() {
+    /**
+     * Activates an observer. This method is automatically called when
+     * a `FlattenedNodesObserver` is created. It should only be called to
+     * re-activate an observer that has been deactivated via the `disconnect` method.
+     */
+    connect() {
       if (isSlot(this._target)) {
         this._listenSlots([this._target]);
       } else {
@@ -72,6 +116,12 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       this._connected = true;
     }
 
+    /**
+     * Deactivates the flattened nodes observer. After calling this method
+     * the observer callback will not be called when changes to flattened nodes
+     * occur. The `connect` method may be subsequently called to reactivate
+     * the observer.
+     */
     disconnect() {
       if (isSlot(this._target)) {
         this._unlistenSlots([this._target]);
@@ -114,6 +164,14 @@ subject to an additional IP rights grant found at http://polymer.github.io/PATEN
       }
     }
 
+    /**
+     * Flushes the observer causing any pending changes to be immediately
+     * delivered the observer callback. By default these changes are delivered
+     * asynchronously at the next microtask checkpoint.
+     *
+     * @return {boolean} Returns true if any pending changes caused the observer
+     * callback to run.
+     */
     flush() {
       if (!this._connected) {
         return;