diff --git a/lib/mixins/property-effects.js b/lib/mixins/property-effects.js
index ee210592c6..122201d3d6 100644
--- a/lib/mixins/property-effects.js
+++ b/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 }));
 }
 
diff --git a/lib/utils/settings.js b/lib/utils/settings.js
index 81241dc5f3..c4c004933d 100644
--- a/lib/utils/settings.js
+++ b/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}