Add a section about crate documentation.

diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md
index 3c6643fbfe1554e0ae02c5bc551f0a04353715c2..6292ba9aac40317c41e590bbc58d549e2f6df179 100644 (file)
--- a/src/doc/book/documentation.md
+++ b/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