Document how to implement "reflect a content attribute"

[jdm]

The macros exist that do this, but there's no clear association between them and the specification text. We should improve our documentation here, and/or rename the macros to make it clearer.

[perlun]

Something like this perhaps (it's just a rough start):

When implementing content attributes for DOM elements, there are a few predefined macros that should be used. These macros are implemented here: https://github.com/servo/servo/blob/master/components/script/dom/macros.rs

These macros are especially useful when implementing properties that "must each reflect the respective content attributes of the same name" (quoting the HTML spec). For a DOM attribute described like that in the specification, these macros should always be used.

• make_getter - Adds an attribute getter for a DOMString attribute.
• make_bool_getter - Adds an attribute getter for a bool attribute.
• make_limited_int_setter - TODO: document
• make_int_getter - Adds an attribute getter for an int attribute.
• make_uint_getter - Adds an attribute getter for an uint attribute.
• etc...

I think it would perhaps be best to keep the documentation for these in the file itself, since there otherwise always a huge risk that we fail in keeping the documentation in sync with the actual implementation.

[jdm]

While I see your point, I'm inclined to have text like that present in dom/bindings/mod.rs, which is where related concepts are documented and therefore easier to find and point people at.

[perlun]

While I see your point, I'm inclined to have text like that present in dom/bindings/mod.rs, which is where related concepts are documented and therefore easier to find and point people at.

Fair enough, I don't know the code well enough yet to have strong opinions about it. 😄 We could add a note in macros.rs saying that "more info on how to use this can be found in x" then.

[nox]

This can probably be salvaged in an E-Easy issue.