Rust: Rust book documentation does not mention "crate documentation"

[gnzlbg]

I just enabled #![deny(missing_docs)] and I get:

error: missing documentation for crate

The section of the book on documentation, however, does not mention anything about "crate documentation" or how to add it.

[steveklabnik]

https://doc.rust-lang.org/book/documentation.html#documenting-modules does mention it, but does not say "crate". Crates have a root module, and that's what the error refers to.

[gnzlbg]

I saw that, guessed that, and it fixed it. It just confused me a bit that the error talks about crate documentation (instead of saying missing documentation for the root module of the crate ...) and In the snippet of code in the docs (the second one for the root module) it just shows the comment, so it wasn't 100% clear to me that the comment is just supposed to float somewhere on the top level of the file.

I think both things could be a bit more clear and a bit more in sync (so it might make sense to label for error messages as well).

[steveklabnik]

I would be happy to work with anyone who wants to tackle this issue.

[GuillaumeRochat]

@steveklabnik I will try to work on this one.

From what I understand, the Documenting Modules part in the rust book should be more explicit about root module and that the module documentation is at the very beginning of the file.

Also, the error should mention root module documentation rather than crate documentation.

[steveklabnik]

Well, the error is fine, as you are missing documentation for the crate.

I think, rather than extending "Documenting modules", a new small section for "Crate documentation" is the way to go, since that's the problem that's trying to be solved. In there, we could explicitly say "You document a crate by putting an inner doc comment (//!) in the crate root, aka lib.rs."

Sound good?

[gnzlbg]

Sounds good to me!

[GuillaumeRochat]

@steveklabnik @gnzlbg Something like that #34667 ?