There do not appear to be descriptions of the purpose of methods in the spec. The definitions linked from the IDL generally say "The foo(parameter) method MUST perform the following steps when invoked:" It would be nice to tell the reader what it does / is used for. For example, "The foo(parameter) method updates the bar with parameter."

For some methods, such as updateRenderState(), the behavior is not obvious, so it's even more important to provide prose telling the reader what to expect.

The description can then be followed by "When this method is invoked, the user agent MUST perform the following steps:"