From d6f3a9ffbb970c498726650431027cd062fb4b40 Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Tue, 16 Jul 2019 18:14:22 -0700
Subject: [PATCH] Added comments.

---
 lib/mixins/property-effects.js | 55 +++++++++++++++++++++++++++-------
 1 file changed, 44 insertions(+), 11 deletions(-)

diff --git a/lib/mixins/property-effects.js b/lib/mixins/property-effects.js
index 0f231335d5..44bd526dd0 100644
--- a/lib/mixins/property-effects.js
+++ b/lib/mixins/property-effects.js
@@ -2666,10 +2666,43 @@ export const PropertyEffects = dedupingMixin(superClass => {
 
     // -- binding ----------------------------------------------
 
+    /*
+     * Overview of binding flow:
+     *
+     * During finalization (`instanceBinding==false`, `wasPreBound==false`):
+     *  `_bindTemplate(false)` called directly during finalization - parses the
+     *  template (for the first time), and then assigns that _prototypical_
+     *  template info to `__preboundTemplateInfo` _on the prototype_; note in
+     *  this case `wasPreBound` is false; this is the first time we're binding
+     *  it, thus we create accessors.
+     *
+     * During first stamping (`instanceBinding==true`, `wasPreBound==true`):
+     *   `_stampTemplate` calls `_bindTemplate(true)`: the `templateInfo`
+     *   returned matches the prebound one, and so this is `wasPreBound == true`
+     *   state; thus we _skip_ creating accessors, but _do_ create a
+     *   sub-instance of the template info to serve as the start of our linked
+     *   list (needs to be an instance, not the prototypical one, so that we can
+     *   add `nodeList` to it to contain the `nodeInfo`-ordered list of instance
+     *   nodes for bindings, and so we can chain runtime-stamped template infos
+     *   off of it). At this point, the call to `_stampTemplate` calls
+     *   `applyTemplateInfo` for each nested `<template>` found during parsing
+     *   to hand prototypical `_templateInfo` to them; we also pass the _parent_
+     *   `templateInfo` to the `<template>` so that we have the instance-time
+     *   parent to link the `templateInfo` under in the case it was
+     *   runtime-stamped.
+     *
+     * During subsequent runtime stamping (`instanceBinding==true`,
+     *   `wasPreBound==false`): `_stampTemplate` calls `_bindTemplate(true)` -
+     *   here `templateInfo` is guaranteed to _not_ match the prebound one,
+     *   because it was either a different template altogether, or even if it
+     *   was the same template, the step above created a sub-instance of the
+     *   info; in this case `wasPreBound == false`, so we _do_ create accessors,
+     *   _and_ link a sub-instance into the linked list.
+     */
+
     /**
-     * Equivalent to static `bindTemplate` API but can be called on
-     * an instance to add effects at runtime.  See that method for
-     * full API docs.
+     * Equivalent to static `bindTemplate` API but can be called on an instance
+     * to add effects at runtime.  See that method for full API docs.
      *
      * This method may be called on the prototype (for prototypical template
      * binding, to avoid creating accessors every instance) once per prototype,
@@ -2677,17 +2710,17 @@ export const PropertyEffects = dedupingMixin(superClass => {
      * create and link an instance of the template metadata associated with a
      * particular stamping.
      *
-     * @override
+     * @override 
      * @param {!HTMLTemplateElement} template Template containing binding
-     *   bindings
+     * bindings
      * @param {boolean=} instanceBinding When false (default), performs
-     *   "prototypical" binding of the template and overwrites any previously
-     *   bound template for the class. When true (as passed from
-     *   `_stampTemplate`), the template info is instanced and linked into
-     *   the list of bound templates.
+     * "prototypical" binding of the template and overwrites any previously
+     * bound template for the class. When true (as passed from
+     * `_stampTemplate`), the template info is instanced and linked into the
+     * list of bound templates.
      * @return {!TemplateInfo} Template metadata object; for `runtimeBinding`,
-     *   this is an instance of the prototypical template info
-     * @protected
+     * this is an instance of the prototypical template info
+     * @protected 
      * @suppress {missingProperties} go/missingfnprops
      */
     _bindTemplate(template, instanceBinding) {