[docs] targetFramerate does not make it clear what units.

[davidmaxwaterman]

The name of the property implies 'Hz', and the words in the comment also imply 'Hz', but it isn't explicit.

Please confirm the units of the target framerate are Hz...ie the intention is to initial-count items are rendered every target-framerate frames.

If I understand correctly, if I set 'initial-count' to '1', and 'target-framerate' to '1', then dom-repeat will attempt to render one additional item per second. Is that correct?

[TimvdLippe]

I think you are right, but would like to hear from @sorvell or @kevinpschaaf to confirm my suspicion.

[kevinpschaaf]

If I understand correctly, if I set 'initial-count' to '1', and 'target-framerate' to '1', then dom-repeat will attempt to render one additional item per second. Is that correct?

No, not quite.

initial-count is how many items will synchronously render upon receiving a new array (regardless of how long it takes), and target-framerate is indeed the fps (frames per second) that it tries to maintain when rendering out the remaining items. The "framerate" is effectively the number of requestAnimationFrames that it tries to allow to actually fire in a given second, and it targets this by empirically measuring the time between rAF's and throttling up/down the number of items created each rAF.

So if you set the target-framerate to 1, you're saying "render as many items as you can in 1000ms, and then yield to paint (and let other tasks run)". How many items it can render is determined empirically over time; faster machines will be able to render more items at a given framerate, so "items per second" is not determinable. On a given machine, higher framerate == fewer items per frame (but higher responsiveness to e.g. event handlers and other rAF-based processing); lower framerate == more items per frame (and lower responsiveness).

[davidmaxwaterman]

Ah, ok. Hrm. Not quite what I had envisioned. I am using dom-repeat with iron-ajax, and wanted to limit the number of requests made per second. That isn't what it is doing. Oh well.
Still, IMO the docs could be clearer on this. Perhaps what you wrote could be added?

[kevinpschaaf]

Yeah, sg. I can add some of that to the API docs.