[ci skip] Add/fix comments per review.

lib/mixins/property-effects.js

@@ -320,6 +320,11 @@ function dispatchNotifyEvent(inst, eventName, value, path) {
   if (path) {
     detail.path = path;
   }
+  // As a performance optimization, we could elide the wrap here since notifying
+  // events are non-bubbling and shouldn't need retargeting. However, a very
+  // small number of internal tests failed in obscure ways, which may indicate
+  // user code relied on timing differences resulting from ShadyDOM flushing
+  // as a result of the wrapped `dispatchEvent`.
   wrap(/** @type {!HTMLElement} */(inst)).dispatchEvent(new CustomEvent(eventName, { detail }));
 }
 

lib/utils/settings.js

@@ -289,7 +289,8 @@ export let suppressTemplateNotifications =
   window.Polymer && window.Polymer.suppressTemplateNotifications || false;
 
 /**
- * Sets `fastDomIf` globally, to put `dom-if` in a performance-optimized mode.
+ * Sets `suppressTemplateNotifications` globally, to disable `dom-change` and
+ * `rendered-item-count` events from `dom-if` and `dom-repeat`.
  *
  * @param {boolean} suppress enable or disable `suppressTemplateNotifications`
  * @return {void}