What is the complete Polymer Public API?

[ghost]

I've read pretty much all there is at https://www.polymer-project.org/docs/polymer/polymer.html. I've also stepped through and poked through a fair amount of the code base. There are several element and instance methods that are accessible, and do not have a leading nor trailing underscore, implying they're not private. However none of them are in any documentation I can find.

Realizing Polymer is still "pre-release" and anything could change at anytime, is there some convention or other document that might clarify which, if any, other accessible methods and functions are considered part of the public API and are safe to use?

[masonlouchart]

I recommend to use the version 0.5.5 or even 0.5.4 for now. But there will huge changes with the next release 0.8.
https://divshot.com/blog/web-components/polymer-0-8-sneak-peek/

[robdodson]

We've talked about the need for an API Reference for a while. At the moment it's on the list of things we want but doesn't have an ETA. cc @nevir and @arthurevans

[nevir]

I think it's unlikely that we'll have an API reference in time for 0.8; probably closer to 0.9 timeframe.

As for 0.5 goes, we're not as consistent as we'd like with underscore prefixed properties. I would assume private unless documented or stated elsewhere (not great, I know). In 0.8 we're doing a lot better marking things as actually private, so it should hopefully be more clear even before the docs land

[ghost]

Thanks for the replies! New to Polymer, and didn't quite realize 0.6 and 0.7 had been skipped and a rather different 0.8 was around the corner. I'm sure you guys will get there with docs, but understand it's a bit easier to write docs around API's that have some future of not changing, than while their signature's may be in flux. You guys are doing great stuff, and anyway you can indicate accessibility in the source is just extra nice stuff.

Somewhat as a tangent; has anyone given any thought at all to potential problems from element names having to live in a global namespace? I doesn't seem like this is on anyone's radar, probably because there just aren't that many elements around yet and therefore there doesn't seem to be a problem. I just know from experience with lots of different languages, that unless something fundamental changes, and assuming Polymer really takes off at some point, we're going to be dealing with multi-hyphenated, long element names, that may still end up conflicting.

I made a proof-of-concept for 0.5.5, that lets element importers specify the name they want to use for the element within their app, as opposed to be forced to use the name the element author thought they should use. Just this simple thing would eliminate any problems with name clashes, and also enable running different versions of the same element side-by-side; also another problem sure to arise should many Polymer Elements, and compositions of them, end up appearing all over the place.

Just curious is all.. Is the thinking that there just won't ever be that many elements, and/or having multi-hyphenated names to effectively namespace everyone away from each won't really be that bad to use and read?

Anyways, Thanks!

[robdodson]

@phestermcs there's been discussion about this but I'm not sure if there are any immediate plans to address it. @dglazkov may know more

[dglazkov]

Namespacing is tracked by https://www.w3.org/Bugs/Public/show_bug.cgi?id=24578 spec bug.