How can I write crate-wide 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!");
}