doc/book/crates-and-modules.md: Doesn't explain where it's legal to declare a mod

[penguin42]

Rust wont let me do (all in one src/)

main.rs:
mod image;

image.rs:
mod string; <<<< 'error: cannot declare a new module at this location'

string.rs:
whatever

I don't see anything in crates-and-modules.md that says it's not possible and/or why.
It does let me add the mod string; in the top level main.rs.
(as a new rust user it doesn't make much sense to me why you can't, since main/rs doesn't use string.rs, but image.rs, so why does main.rs care)

[pnkfelix]

FYI The reason for this restriction is documented as part of rust-lang/rfcs#63 (RFC 63 text). In particular, the Motivation section of that RFC lays out an example that shows a footgun for new users when putting mod filename; into modules other than mod.rs/lib.rs

I agree that the Rust documentation in crates-and-modules.md should probably point out the restrictions on where mod filename; can be used explicitly.

[steveklabnik]

We are not improving the existing book ourselves, as we're re-writing it over at https://github.com/rust-lang/book, and this chapter has completely changed. If you or anyone else would like to improve this, please send in a PR, and/or read the new book and file an issue over there if it's still deficient in this way. But we're not keeping bugs open that track problems with the book's text. Thanks!