rustdoc: Document what's going on throughout

This addresses some of @huonw's in #9691 about the startling lack of
documentation guiding one throughout the innards of rustdoc::html
auto merge of #9704 : alexcrichton/rust/rustdoc-comments, r=huonw

This addresses some of @huonw's in #9691 about the startling lack of
documentation guiding one throughout the innards of rustdoc::html

r? @huonw