Document layout dirtiness flags, restyle hints, etc.

[Ms2ger]

All this code seems amazingly complex and brittle. We should clearly document the exact constraints and invariants, and how we ensure they hold.

CC @pcwalton @bholley

[bholley]

Restyle hints are pretty well-documented (see the comments in restyle_hints.rs).

The |dirty| flag is not well-documented, possibly because its semantics are somewhat ill-defined and need improvement. At the moment, |dirty| is basically a union indicating that at least one of the following is true:

• If element-valued, we need to re-run selector matching on it.
• We need to regenerate style structs (see #8438 for how this case differs from the above)
• We need to reflow/repaint the node (if, say, the text content changed)

There may be others (I'm figuring this out as I go along). All this code could certainly benefit from additional cleanup.

[asajeffrey]

I probably didn't help, by highjacking dirtiness for DOM versioning and cache invalidation of HTMLCollection objects. A tidy up would help.

[nox]

These are documented now, AFAICT.