Comments in WebRender

WebRender has historically been sparsely-commented. This adds hurdles for new contributors, and saps the productivity of experts who must spend time answering their questions on IRC.

We believe that documentation works best in-tree, as close to the relevant code as possible. Our aim is for an experienced engineer to be able to understand the code by simply reading it.

We measure progress towards this goal by the percentage of the code that can be compiled with deny(missing_docs). Using rustdoc syntax and conventions has the follow advantages:

• The compiler can enforce it.
• We get auto-generated HTML documentation for free.
• Our commenting conventions are consistent with the rest of the Rust ecosystem.

The path to deny(missing_docs) for the entire codebase has two parts. First, we require the following of all new contributions:

• Any new modules should have deny(missing_docs).
• Any new methods, members, enums, variants, structs, traits, etc should satisfy the doc checker, even if the surrounding code does not.

Second, contributors are encouraged to spend time improving the documentation of existing code they encounter. This might mean adding documentation to methods or variants adjacent to a new addition, or to code that the author struggled to understand. If you find yourself digging or asking to determine what something does, others will likely repeat your work in the future if you don't capture the answer in a comment.