Polymer 2.0 issues

[aomarks]

The following are the remaining TypeScript issues with the Polymer 2.0 core library.

Missing APIs:

• Polymer() legacy registration function
• Polymer.ArraySplice.calculateSplices
• Polymer.Async.animationFrame.run
• Dynamically "forwarded" APIs on Polymer.DomApi (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L234).
• Polymer.dom.flush (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L330)
• Polymer.dom.addDebouncer (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L340)
• All the getters fromEventApi (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L256).

Things we shouldn't emit:

• polymer/lib/utils/templatize.d.ts(40,15): error TS2300: Duplicate identifier 'klass'.

Missing types:

• polymer/lib/legacy/class.d.ts(79,24): error TS2304: Cannot find name 'PolymerInit'.
• polymer/lib/mixins/element-mixin.d.ts(74,13): error TS2304: Cannot find name -
  'StampedTemplate'.
• polymer/lib/mixins/property-effects.d.ts(50,19): error TS2304: Cannot find name 'Polymer_PropertyEffects'.
• polymer/lib/mixins/property-effects.d.ts(59,23): error TS2304: Cannot find name 'TemplateInfo'.
• polymer/lib/utils/async.d.ts(14,38): error TS2304: Cannot find name 'AsyncInterface'.
• polymer/lib/utils/async.d.ts(23,29): error TS2304: Cannot find name 'IdleDeadline'.
• polymer/lib/utils/debounce.d.ts(14,28): error TS2304: Cannot find name 'AsyncModule'.
• polymer/lib/utils/gestures.d.ts(35,30): error TS2304: Cannot find name 'GestureRecognizer'.
• polymer/lib/utils/mixin.d.ts(11,33): error TS2304: Cannot find name 'T'.

Other:

• Namespaces don't have descriptions.
• Handle visibility. Exclude private things entirely?
• Don't reference Shady CSS typings, because we aren't generating any (at least for now).
• Polymer.Element does not inherit PropertyEffects mixin, so set() etc. are missing.
• Respect @appliesMixin annotation.
• Some things have a @summary annotation but no main description (e.g. the Polymer.ArraySplice namespace). What do we do with @summary vs description?
• Output to types directory, if that's what we decide.
• Many Polymer APIs are missing !s on their @params which they should have (e.g. calculateSplices), so they come out as |null.

[43081j]

Quite a few methods end up with a return type of any. An example of this is ready().

We should probably add @return {void} to all of these in polymer its self, or detect that the method never returns so we can infer it is void. We can't really safely assume "no return comment" means it returns void, so we should probably just add the missing comments eventually.

Also, a nice thing to have would be to make use of the @appliesMixin jsdoc comment so we can make mixins correctly return an inheriting type (such as T & ElementMixin & PropertyEffectsMixin). This will help avoid repeatedly defining things like ready().

Great work so far, looking good 👍

[43081j]

@aomarks just noticed what seems like a rather clear problem while trying the generated types out...

It seems the generator didn't figure out that Polymer.Element inherits the property effects mixin, so it has no type information for things like set(...) and what not.

https://github.com/Polymer/polymer/blob/1fbb5041d95468d5412317205a235eccc0cda21f/lib/mixins/element-mixin.html#L100

[aomarks]

Typings are in Polymer master as of Polymer/polymer#4928. Closing this issue. The remaining items can be tracked at the issues below:

Dynamically "forwarded" APIs on Polymer.DomApi (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L234).

Tracking at Polymer/polymer#5010. These methods are forwarded with a utility function that means Analyzer does not detect them.

Polymer.dom.flush (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L330)
Polymer.dom.addDebouncer (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L340)

Tracking at https://github.com/Polymer/polymer-analyzer/issues/752. Top-level function assignments are not picked up by Analyzer, even if they have a @function annotation.

All the getters fromEventApi (https://github.com/Polymer/polymer/blob/master/lib/legacy/polymer.dom.html#L256).

Tracking at https://github.com/Polymer/polymer-analyzer/issues/645. Analyzer needs support for scanning getters.