Templatizer really needs better documentation and deserves mention in developer guide

[David-Mulder]

Per title, the Templatizer documentation can hardly be found (I ended up just reading it from the file itself and only found out today it can be found in the API reference as well). Additionally even when you have the current documentation a lot of things are unclear:

• _forwardParentPath/_forwardParentProp Still not sure when these functions are triggered despite having build two full elements with Templatizer, but I have never been able to trigger those.
• _getRootDataHost is absolutely crucial when you want to use functions inside those templates, but isn't mentioned in the standard documentation
• The idea that _instanceProps is used for any properties that should be handled by the element itself isn't exactly clear either.
• Explain how a single custom element can templatize multiple <template>'s (still no idea).
• The idea that you have to observe your 'input' data for changes and propagate those to your instances. (It's relatively obvious once you get the idea behind Templatizer, but far from obvious when you start.

[arthurevans]

@kevinpschaaf should we be documenting Templatizer for people to use, or should we treat it as an implementation detail of dom-repeat, etc.? As @David-Mulder said, we don't supply enough information now to get people up and running.

[David-Mulder]

@arthurevans Honestly, <dom-repeat> is nice and all if you're doing simple stuff, but as soon as you get into the area of making more complex 'base' elements you really start to need Templatizer (e.g. David-Mulder/paper-datatable ) and even for something simple like David-Mulder/leather-editable-list I do not think it's possible to replicate an element like that without Templatizer. (With the second one I might be mistaken though, but I don't think I am.)

[bedeoverend]

+1 I would love to see templatizer documented and maintained for public consumption. My particular use case is for constructing page layouts dynamically by passing templates to an element to bind and stamp (see https://github.com/simplaio/template-yield). It'd be great to see the data binding in templatizer further explained - could imagine it being a really powerful / useful tool.

[Buslowicz]

+1 from me as well. I tried to build dom-switch and template-loader (something like @bedeoverend 's project), but failed due to lack of a proper documentation on how to use it. Please guys, make a proper doc, not just comments.

[eob]

+1 here Data passed into the template with stamp doesn't act as it would with a normal template -- dom-repeat doesn't seem to work, {{complexObjectReference}} outputs the toString() of the object, etc.

Since there's no documentation, it's unclear how to work around these issues (or if they're even expected in the first place).

[nicholaswmin]

+1

[ghost]

To help me prioritize and manage issues in the repo, I'll close this issue with no docs changes in 7 days. To prevent this, please comment within 7 days.

[arthurevans]

The 2.x version of this is on my plate, but realistically not going to happen before next quarter, at the earliest.

[iSuslov]

https://www.polymer-project.org/2.0/docs/api/namespaces/Polymer.Templatize misleading docs. In https://github.com/Polymer/polymer/issues/4458 you can see that Polymer.Templatize.templatize(template, this, {}) only works when all three parameters are passed. Please fix it.