From 0ede79afdf125720019d1d32c169a1c40e579d78 Mon Sep 17 00:00:00 2001
From: Steven Orvell <sorvell@google.com>
Date: Tue, 13 Oct 2015 11:48:59 -0700
Subject: [PATCH] Add docs

---
 src/lib/dom-api-classlist.html                |  6 +++
 src/lib/dom-api-event.html                    | 10 +++++
 src/lib/dom-api-flush.html                    |  9 ++++-
 ...=> dom-api-observe-distributed-nodes.html} | 18 ++++++---
 ...tation.html => dom-api-observe-nodes.html} | 19 ++++++---
 src/lib/dom-api.html                          | 40 ++++++++++++++++---
 src/mini/shady.html                           |  7 +---
 7 files changed, 87 insertions(+), 22 deletions(-)
 rename src/lib/{dom-api-mutation-content.html => dom-api-observe-distributed-nodes.html} (74%)
 rename src/lib/{dom-api-mutation.html => dom-api-observe-nodes.html} (88%)

diff --git a/src/lib/dom-api-classlist.html b/src/lib/dom-api-classlist.html
index 7b405ad186..d4ce7b7f38 100644
--- a/src/lib/dom-api-classlist.html
+++ b/src/lib/dom-api-classlist.html
@@ -14,6 +14,12 @@
 
   var DomApi = Polymer.DomApi.ctor;
 
+  /**
+   * DomApi.classList allows maniuplation of `classList` compatible with 
+   * Polymer.dom. The general usage is 
+   * `Polymer.dom(node).classList.method(arguments)` where methods and arguments
+   * match native DOM.
+   */
   Object.defineProperty(DomApi.prototype, 'classList', {
     get: function() {
       if (!this._classList) {
diff --git a/src/lib/dom-api-event.html b/src/lib/dom-api-event.html
index fff14f980a..d13480809f 100644
--- a/src/lib/dom-api-event.html
+++ b/src/lib/dom-api-event.html
@@ -15,6 +15,16 @@
   var DomApi = Polymer.DomApi.ctor;
   var Settings = Polymer.Settings;
 
+  
+  /**
+   * DomApi.Event allows maniuplation of events compatible with 
+   * the scoping concepts in Shadow DOM and compatible with both Shady DOM 
+   * and Shadow DOM. The general usage is 
+   * `Polymer.dom(event).property`. The `path` property returns `event.path` 
+   * matching Shadow DOM. The `rootTarget` property returns the first node 
+   * in the `path` and is the original event target. The `localTarget` property
+   * matches event.target under Shadow DOM and is the scoped event target.
+   */
   DomApi.Event = function(event) {
     this.event = event;
   };
diff --git a/src/lib/dom-api-flush.html b/src/lib/dom-api-flush.html
index 1ecc1821e6..82449b92ac 100644
--- a/src/lib/dom-api-flush.html
+++ b/src/lib/dom-api-flush.html
@@ -9,7 +9,14 @@
 -->
 <script>
 
-  // add Polymer.dom flush api...
+  /** 
+   * `Polymer.dom.flush()` causes any asynchronously queued actions to be 
+   * flushed synchronously. It should be used sparingly as calling it frequently
+   * can negatively impact performance since work is often deferred for 
+   * efficiency. Calling `Polymer.dom.flush()` is useful, for example, when 
+   * an element has to measure itself and is unsure about the state of its 
+   * internal or compoased DOM.
+   */
   Polymer.Base.extend(Polymer.dom, {
     
     _flushGuard: 0,
diff --git a/src/lib/dom-api-mutation-content.html b/src/lib/dom-api-observe-distributed-nodes.html
similarity index 74%
rename from src/lib/dom-api-mutation-content.html
rename to src/lib/dom-api-observe-distributed-nodes.html
index 1765c23d24..1cb6438030 100644
--- a/src/lib/dom-api-mutation-content.html
+++ b/src/lib/dom-api-observe-distributed-nodes.html
@@ -15,13 +15,21 @@
     var DomApi = Polymer.DomApi.ctor;
     var Settings = Polymer.Settings;
 
-    DomApi.MutationContent = function(domApi) {
-      DomApi.Mutation.call(this, domApi);
+    /**
+     * DomApi.ObserveDistributedNodes notifies when the list returned by 
+     * a <content> element's `getDistributedNodes()` may have changed.
+     * It is not meant to be used directly; it is used by
+     * `Polymer.dom(node).observeNodes(callback)` to observe changes to
+     * `<content>.getDistributedNodes()`.
+     */
+    DomApi.ObserveDistributedNodes = function(domApi) {
+      DomApi.ObserveNodes.call(this, domApi);
     };
 
-    DomApi.MutationContent.prototype = Object.create(DomApi.Mutation.prototype);
+    DomApi.ObserveDistributedNodes.prototype = 
+      Object.create(DomApi.ObserveNodes.prototype);
 
-    Polymer.Base.extend(DomApi.MutationContent.prototype, {
+    Polymer.Base.extend(DomApi.ObserveDistributedNodes.prototype, {
 
       // NOTE: ShadyDOM distribute provokes notification of these observers
       // so no setup is required.
@@ -41,7 +49,7 @@
 
     if (Settings.useShadow) {
       
-      Polymer.Base.extend(DomApi.MutationContent.prototype, {
+      Polymer.Base.extend(DomApi.ObserveDistributedNodes.prototype, {
         
         // NOTE: Under ShadowDOM we must observe the host element for
         // changes.
diff --git a/src/lib/dom-api-mutation.html b/src/lib/dom-api-observe-nodes.html
similarity index 88%
rename from src/lib/dom-api-mutation.html
rename to src/lib/dom-api-observe-nodes.html
index e3a311566e..b4b27bb884 100644
--- a/src/lib/dom-api-mutation.html
+++ b/src/lib/dom-api-observe-nodes.html
@@ -16,13 +16,19 @@
     var Settings = Polymer.Settings;
     var hasDomApi = Polymer.DomApi.hasDomApi;
 
-    DomApi.Mutation = function(domApi) {
+    /**
+     * DomApi.ObserveNodes tracks changes to an element's effective child nodes,
+     * the same list returned from `Polymer.dom(node).getEffectiveChildNodes()`.
+     * It is not meant to be used directly; it is used by
+     * `Polymer.dom(node).observeNodes(callback)` to observe changes.
+     */
+    DomApi.ObserveNodes = function(domApi) {
       this.domApi = domApi;
       this.node = this.domApi.node;
       this._listeners = [];
     };
 
-    DomApi.Mutation.prototype = {
+    DomApi.ObserveNodes.prototype = {
 
       addListener: function(callback) {
         if (!this._isSetup) {
@@ -167,12 +173,13 @@
 
     if (Settings.useShadow) {
 
-      var baseSetup = DomApi.Mutation.prototype._setup;
-      var baseCleanup = DomApi.Mutation.prototype._cleanup;
+      var baseSetup = DomApi.ObserveNodes.prototype._setup;
+      var baseCleanup = DomApi.ObserveNodes.prototype._cleanup;
 
-      var beforeCallListeners = DomApi.Mutation.prototype._beforeCallListeners;
+      var beforeCallListeners = DomApi.ObserveNodes
+        .prototype._beforeCallListeners;
 
-      Polymer.Base.extend(DomApi.Mutation.prototype, {
+      Polymer.Base.extend(DomApi.ObserveNodes.prototype, {
         
         _setup: function() {
           if (!this._observer) {
diff --git a/src/lib/dom-api.html b/src/lib/dom-api.html
index 9d4067eb4f..f85e7cf02c 100644
--- a/src/lib/dom-api.html
+++ b/src/lib/dom-api.html
@@ -11,6 +11,12 @@
 <link rel="import" href="dom-innerHTML.html">
 <script>
 
+  /**
+   * DomApi is a dom manipulation library which is compatible with both 
+   * Shady DOM and Shadow DOM. The general usage is 
+   * `Polymer.dom(node).method(arguments)` where methods and arguments
+   * match native DOM where possible.
+   */
   Polymer.DomApi = (function() {
     'use strict';
 
@@ -462,6 +468,11 @@
         return list;
       },
 
+      /*
+        Returns a list of effective childNoes within this element. These can be
+        dom child nodes or elements distributed to children that are insertion
+        points.
+      */
       getEffectiveChildNodes: function() {
         var list = [];
         var c$ = this.childNodes;
@@ -526,15 +537,34 @@
         return n;
       },
 
+      /**
+       * Notifies callers about changes to the element's effective child nodes, 
+       * the same list as returned by `getEffectiveChildNodes`. 
+       * @param {function} callback The supplied callback is called with an 
+       * `info` argument which is an object that provides 
+       * the `target` on which the changes occurred, a list of any nodes 
+       * added in the `addedNodes` array, and nodes removed in the 
+       * `removedNodes` array.
+       * @return {object} Returns a handle which is the argument to 
+       * `unobserveNodes`.
+       */
       observeNodes: function(callback) {
-        if (!this.observer) {
-          this.observer = this.node.localName === CONTENT ?
-            new DomApi.MutationContent(this) :
-            new DomApi.Mutation(this);
+        if (callback) {
+          if (!this.observer) {
+            this.observer = this.node.localName === CONTENT ?
+              new DomApi.ObserveDistributedNodes(this) :
+              new DomApi.ObserveNodes(this);
+          }
+          return this.observer.addListener(callback);
         }
-        return this.observer.addListener(callback);
       },
 
+      /**
+       * Stops observing changes to the element's effective child nodes.
+       * @param {object} handle The handle for the callback that should
+       * no longer receive notifications. This handle is returned from 
+       * `observeNodes`.
+       */
       unobserveNodes: function(handle) {
         if (this.observer) {
           this.observer.removeListener(handle);
diff --git a/src/mini/shady.html b/src/mini/shady.html
index febe2cb0d4..34da3dbe5f 100644
--- a/src/mini/shady.html
+++ b/src/mini/shady.html
@@ -12,18 +12,15 @@
 <link rel="import" href="../lib/dom-api-flush.html">
 <link rel="import" href="../lib/dom-api-event.html">
 <link rel="import" href="../lib/dom-api-classlist.html">
-<link rel="import" href="../lib/dom-api-mutation.html">
-<link rel="import" href="../lib/dom-api-mutation-content.html">
+<link rel="import" href="../lib/dom-api-observe-nodes.html">
+<link rel="import" href="../lib/dom-api-observe-distributed-nodes.html">
 <script>
 
   (function() {
     /**
-
       Implements a pared down version of ShadowDOM's scoping, which is easy to
       polyfill across browsers.
-
     */
-
     var hasDomApi = Polymer.DomApi.hasDomApi;
 
     Polymer.Base._addFeature({