Add comments re: instanceProps

lib/utils/templatize.html

@@ -102,6 +102,8 @@
             this._setPendingProperty(hprop, this.__dataHost['_host_' + hprop]);
           }
         }
+        // Any instance props passed in the constructor will overwrite host props;
+        // normally this would be a user error but we don't specifically filter them
         for (let iprop in props) {
           this._setPendingProperty(iprop, props[iprop]);
         }
@@ -391,12 +393,11 @@
      *     // Customize property forwarding and event model decoration
      *     let TemplateClass = Polymer.Templatize.templatize(template, this, {
      *       parentModel: true,
-     *       instanceProps: {...},
      *       forwardHostProp(property, value) {...},
+     *       instanceProps: {...},
      *       notifyInstanceProp(instance, property, value) {...},
      *     });
      *
-     *
      * @namespace
      * @memberof Polymer
      * @summary Module for preparing and stamping instances of templates
@@ -448,6 +449,15 @@
        *   from `instance.parentModel` in cases where template instance nesting
        *   causes an inner model to shadow an outer model.
        *
+       * When `options.forwardHostProp` is declared as an option, any properties
+       * referenced in the template will be automatically forwarded from the host of
+       * the `<template>` to instances, with the exception of any properties listed in
+       * the `options.instanceProps` object.  `instanceProps` are assumed to be
+       * managed by the owner of the instances, either passed into the constructor
+       * or set after the fact.  Note, any properties passed into the constructor will
+       * always be set to the instance (regardless of whether they would normally
+       * be forwarded from the host).
+       *
        * Note that the class returned from `templatize` is generated only once
        * for a given `<template>` using `options` from the first call for that
        * template, and the cached class is returned for all subsequent calls to