How can I write crate-wide documentation? - documentation

Question

In order to ensure that all public artifacts of my crate are documented (if minimally to start with), I specified #![deny(missing_docs)] in my lib.rs. This backfired.
I expected to write a documentation comment at the top and the code afterwards:
/// Hello world example for Rust.
#![deny(missing_docs)]
fn main() {
println!("Hello world!");
}
This fails with:
error: an inner attribute is not permitted following an outer doc comment
--> src/main.rs:3:3
|
3 | #![deny(missing_docs)]
| ^
|
= note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the beginning of source files. Outer attributes, like `#[test]`, annotate the item following them.
Reverting the order so that the attribute is first and the comment second:
#![deny(missing_docs)]
/// Hello world example for Rust.
fn main() {
println!("Hello world!");
}
Also fails:
error: missing documentation for crate
--> src/main.rs:1:1
|
1 | / #![deny(missing_docs)]
2 | |
3 | | /// Hello world example for Rust.
4 | |
5 | | fn main() {
6 | | println!("Hello world!");
7 | | }
| |_^
|
note: lint level defined here
--> src/main.rs:1:9
|
1 | #![deny(missing_docs)]
| ^^^^^^^^^^^^
I could not find how to actually write documentation for the crate itself. How should I be writing the crate's documentation to satisfy #![deny(missing_docs)]?

Answer 1

I found the hidden nugget in the book's Publishing a Crate to Crates.io section.
Regular documentation comments (starting with ///) document the next item, however a crate is nobody's next.
The solution is to switch to using another kind of comment, this time starting with //!, which documents the enclosing item.
And suddenly it works:
#![deny(missing_docs)]
//! Hello world example for Rust.
fn main() {
println!("Hello world!");
}