The state of the docs need to improve

[Marco Scannadinari]

# Sorry if the title and/or the following content is incorrect - I'm pretty tired.

There are inherent complications in using Polymer elements. Undocumented detail about where my dear elements will be taken and grafted inside whatever custom element I use or its N number of children really take up a lot of time trying to debug trivial implementation stuff.

For instance, very recently I was using core-header-panel, and tweaking some flexbox properties to get a desired layout, however, for some reason, any !core-toolbar elements don't fill the remaining size using a 'flex' attribute, or height: 100%. Even checking the core-header-panel shadow tree, the insertion point has a 100% height, and yet my content only takes up the minimum space for its children. Using the 'fit' attribute works, however (no idea why), and so does taking the core-header-panel's children out of a core-header-panel.

This is not an isolated example, I also experienced such a quirk when using core-toolbar. It turns out that it already is display: flex, and confused me a lot when I had manually applied display: flex to it, hopelessly leading to systematic error, sure to be repeated throughout the development process...

The point I'm making is that the poor users of Polymer shouldn't need to dig into the source to find answers (didn't even work in my case). The docs need to improve to make up for the unavoidable reality of custom elements and shadow DOM. I do hope that this post won't be ignored because these problems occur frequently and stifles developer productivity and in my case, motivation.

Please, developers - people who *understand* the source - spend a bit more time on the docs for the sake of us all :)

[Frankie Fu]

Sorry to hear about your unpleasant experience.  Those elements (core-header-panel and core-toolbar) are already providing specific layouts so they don't work well when you try to use layout attributes on them.  We definitely need to have docs to explain that.  In general, the core/paper elements are not perfect and the docs need to be improved.  We are working on that.  If you do find things missing or not clear in the docs please feel free to file issues on github and we will try to address them as well.

Follow Polymer on Google+: plus.google.com/107187849809354688692
---
You received this message because you are subscribed to the Google Groups "Polymer" group.
To unsubscribe from this group and stop receiving emails from it, send an email to polymer-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/polymer-dev/00fb39ed-fcda-4aaa-b682-3135bb210c9b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.