rustdoc documentation deserves more prominent coverage

[ericseppanen]

A colleague new to Rust didn't know what /// comments were, and were surprised that they hadn't seen them in the Rust Book. I was quite surprised at this: I think proper code documentation deserves a more prominent placement.

Section 3.4 ("Comments") doesn't mention rustdoc comments or ///.
Chapter 11 ("Writing Automated Tests") doesn't mention doctests.

They are mentioned in section 14.2 ("Publishing a Crate to Crates.io"), but that's a section new people are very likely to skip over. It's also wedged between "Customizing Builds with Release Profiles" and "Cargo Workspaces", so it's clearly not a chapter for beginners.

This is a missed opportunity, because consistently documented code is a good idea everywhere, and starts long before code gets published to the world.

None of the code examples in other chapters contain rustdoc comments, which is another missed chance to set a good example.

[carols10cents]

Section 3.4 does mention documentation comments

[ericseppanen]

Section 3.4 does mention documentation comments

True, but I don't think it really addresses my concern.

Maybe I could offer a more concrete suggestion: I think the doc-comment section from 14.2 should be moved into section 3.4. The part about doc-tests might be more at home in chapter 11.

HTML docs on a public crate are not the only use case of doc comments. Rust-analyzer can show documentation in the editor, which is useful even for non-published crates.

But I think the more fundamental question is: should new rust coders start out documenting functions with //? I think the answer is no, it's preferable to teach them /// right away. Moving /// to chapter 3 would be a good push in this direction.