Update AnimFrame docs with info about when paint happens.

[xStrom]

The AnimFrame docs were still from an era before we had partial invalidation. Nowadays an AnimFrame event does not necessarily lead to a paint, because paint is guarded by a check for invalid regions existing.

I also fixed a few rustdoc warnings around doc formating.

[jneem]

I'll give you the green button because it's clearly an improvement, but I left a comment anyway...

[jneem]

I think this applies in general, not just when handling an AnimFrame event: request_anim_frame doesn't invalidate anything and so if you're animating then you still need to invalidate. Maybe it's just me, but I find the "request a frame" / "invalidate a rect" distinction more natural than trying to distinguish between "animation frame" and "actual rendered frame"

[xStrom]

Yeah it's definitely general, my writing was just coming from a space where MouseDown never meant paint, but AnimFrame used to mean that (as the comment also said).

I'll see if I can adjust the wording a bit to be more precise about lack of invalidation being the issue.

[xStrom]

As another note, I actually ran into an issue with an older app of mine that used AnimFrame to measure render fps but the widget itself only painted when the fps changed. Thus the comment's purpose was to make sure it's documented that such tricks no longer work.

[xStrom]

Alright I rewrote the docs with a more general focus and using common Druid terms like paint instead of talking about rendering which is a Druid internal term.

Does it look better now @jneem?

[jneem]

Yep, that looks clear to me!