Better documentation for "No more mod.rs"

[KiChjang]

https://rust-lang-nursery.github.io/edition-guide/rust-2018/module-system/path-clarity.html#no-more-modrs

In Rust 2018, mod.rs is no longer needed. foo.rs can just be foo.rs, and the submodule is still foo/bar.rs. This eliminates the special name, and if you have a bunch of files open in your editor, you can clearly see their names, instead of having a bunch of tabs named mod.rs.

Emphasis mine. I discovered that this does not mean that mod.rs can be eliminated from your projects once and for all -- instead, it means specifically that in the case where you have only src/foo/mod.rs, you can instead name it src/foo.rs and it'll work just fine.

[KiChjang]

Further investigation has caused me to believe that the intended way of having no mod.rs is to first have a src/foo.rs, and then have src/foo/bar.rs, which would cause use self::foo::bar; to succeed.

[ZhangHanDong]

@KiChjang Agree with you.

[steveklabnik]

It's not clear to me what this ticket means. Could you help point me to what needs to be clarified?

[KiChjang]

@steveklabnik It's not clear from the documentation that if you transition from a project that had a src/foo/mod.rs before means that you need to rename and move that file to src/foo.rs. My initial reading of it felt like you could just remove src/foo/mod.rs altogether and the project would still compile, leading to surprises when I attempted to import self::foo::bar, where bar is any submodule under foo.

[steveklabnik]

Do you have any suggestions on what should change? I'm having a hard time seeing how you got to that. I'd still like to improve this though!

[KiChjang]

Perhaps instead of saying that mod.rs is no longer needed, it may be better to say that you can replace src/foo/mod.rs with src/foo.rs, because the module (and hence the functionality of mod.rs) is still being declared; it's just not called mod.rs anymore and not located in the same location.

Conversations with @ZhangHanDong has informed (or really, reminded) me that this is how Rails imported its modules, so perhaps there is some text in the Rails documentation that we could reference...

[ZhangHanDong]

@steveklabnik @KiChjang

I submitted a PR

[ZhangHanDong]

@KiChjang PR have been merged. this issues should be closed.

[Timmmm]

Sorry but the documentation is still not clear:

In Rust 2015, if you have a submodule:

///  foo.rs
///  or
///  foo/mod.rs

mod foo;

It can live in foo.rs or foo/mod.rs. If it has submodules of its own, it must be foo/mod.rs. So a bar submodule of foo would live at foo/bar.rs.

This is ok, but:

In Rust 2018, mod.rs is no longer needed.

///  foo.rs
///  foo/bar.rs

mod foo;

/// in foo.rs
mod bar;

Sorry what? It is not clear at all what is in which file. Following the above example it seems to say that mod foo; should be in foo.rs or foo/bar.rs (surely not?), and mod bar; should ... also .. be in foo.rs?? What is the intended directory structure here?

Also I would have thought that foo/foo.rs was a reasonable place to look for mod foo;. That way you can put all of the code for a module (and its submodules) in its own directory. It seems like "no more mod.rs" means "no more mod.rs as long as you don't mind module code spewing into its parent directory?"

[Timmmm]

Here is a better way to word it I think:

In Rust 2015 if you declare mod foo; it will look for the module in the following places (relative to the file containing the mod foo; declaration):

• foo.rs
• foo/mod.rs

However if the foo module has submodules of its own it must be at foo/mod.rs. A submodule bar could be at foo/bar.rs or foo/bar/mod.rs.

In Rust 2018 this restriction is lifted. If the foo module is implemented in foo.rs Rust will look for its bar submodule at foo/bar.rs or foo/bar/mod.rs.

Assuming that is correct.

[ehuss]

@Timmmm I have posted a PR at #187. Can you take a look and let me know what you think?

[Timmmm]

Much clearer, thanks! I think it is probably also worth highlighting the fact that if you want to keep all of your module files in a subdirectory, you still have to use mod.rs. Initially when I heard "no need to use mod.rs anymore!" I thought I would just be able to rename mod.rs to foo.rs, or something like that, but that isn't the case (presumably because that file is already used for foo::foo). Something like this at the end:

If you wish to keep all foo-related files in the foo directory then you must still use mod.rs. You cannot simply rename foo/mod.rs to foo/foo.rs because that is the path for a submodule of foo, also called foo.