Rollup merge of rust-lang#34667 - KaivoAnastetiks:fix/crate-documentation, r=Manishearth

Add a section about crate documentation.

Fixes rust-lang#34329
?r @steveklabnik

Author: steveklabnik

src/doc/book/documentation.md

@@ -486,6 +486,17 @@ you have a module in `foo.rs`, you'll often open its code and see this:
 //! The `foo` module contains a lot of useful functionality blah blah blah
 ```
 
+### Crate documentation
+
+Crates can be documented by placing an inner doc comment (`//!`) at the
+beginning of the crate root, aka `lib.rs`:
+
+```rust
+//! This is documentation for the `foo` crate.
+//!
+//! The foo crate is meant to be used for bar.
+```
+
 ### Documentation comment style
 
 Check out [RFC 505][rfc505] for full conventions around the style and format of