Better documentation for "No more mod.rs" about edition-guide

[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.

[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...

[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.

[jinmingjian]

@Timmmm Yes. I eliminate the mod.rs in my project. And in fact, I've seen several big projects done this. OK, YMMV. But I suggest who read this issue can do your own try.

[art-in]

I've tried both structures (with and without mod.rs), and it works ok in both editions (2015 and 2018).

└── foo/
    ├── mod.rs
    └── bar.rs

├── foo.rs
└── foo/
    └── bar.rs

The section is confusing, as I'm new to rust. Let me clarify.

In Rust 2015 ... It (mod foo) can live in foo.rs or foo/mod.rs. If it has submodules of its own, it must be foo/mod.rs.

I have edition 2015, foo has submodules, and still I can put it in both foo.rs and foo/mod.rs.
The restriction existed in 2015 before, but was eliminated at some point, right?

No more mod.rs

I have no errors for having mod.rs in both editions.
It means, "mod.rs is not required anymore" (for modules with submodules), right?

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.

That's why e.g. vscode shows path when several tabs with same names are opened.

So if I prefer mod.rs, it is still ok to use it, right?

[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!

[ZhangHanDong]

@steveklabnik @KiChjang

I submitted a PR

[ZhangHanDong]

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

[ehuss]

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

[jinmingjian]

I re-read this chapter again today. These words in this changed section have problem truly.

what Timmmm said above's above... is right. The comments for mod decl after "In Rust 2018..."

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

mod foo;
...

make no sense ... two files? which files?

The fact should be that "mod foo" should be declared in its parent(mod), like in "lib.rs".

@Timmmm your above idea is not right. "No more mod.rs" is true. You can have no mod.rs for modules now. I suggest you do some tries. This is why I/we should advocate the 2018 style.

So, I suggest to reopen this idea and correct the problem.

[ehuss]

@jinmingjian Have you seen the rewritten version? It is available in the beta or nightly docs: https://doc.rust-lang.org/beta/edition-guide/rust-2018/module-system/path-clarity.html#no-more-modrs This should hit stable next week (it unfortunately takes a while to ride the train to stable).

[jinmingjian]

@ehuss thanks for pointing this beta edition-guide! It is great!

It is interesting to see we do different changes to different versions of the same docs. A little mess...

OK, I may live with nightly docs: https://doc.rust-lang.org/nightly/edition-guide/rust-2018/module-system/path-clarity.html#no-more-modrs , rather than fooled by the search engine:smiley:.

[Timmmm]

@Timmmm your above idea is not right. "No more mod.rs" is true

No it isn't. It is "No more mod.rs if you are ok with moving the (former) mod.rs file into its parent directory".

To put it another way, "no more mod.rs" implies that there is never any reason to use mod.rs any more. But actually you can only eliminate mod.rs if you structure your files in a quite awkward way (IMO).

[ehuss]

The restriction existed in 2015 before, but was eliminated at some point, right?
It means, "mod.rs is not required anymore" (for modules with submodules), right?
So if I prefer mod.rs, it is still ok to use it, right?

Support for non-mod-rs files was stabilized in both editions in the 1.31 release. You are free to use either style on both editions.

Some of the confusion may be because the edition guide was written in such a way that "Rust 2015" meant how code was written around the 1.0 release, and "2018" was how code can be written after the 1.31 release. It sort of provides the highlights of the changes in the 3 years between May 2015 and Dec 2018. It does not necessarily mean certain things can only be done when you declare the edition as "2018". There is a page at https://doc.rust-lang.org/edition-guide/rust-2018/edition-changes.html that explicitly lists the actual differences between the two.

[art-in]

Ok, I would at least add something like this to the end of this section:
"Both approaches are allowed in editions 2015 and 2018 starting from v1.31".

Also I would change it's title, since it's misleading ("No more mod.rs").
It's obviously aligned with "No more extern crate" title, but it makes more sense for extern crate as it just doesn't do anything anymore, while mod.rs is still valid approach if you want to keed your module in self-contained folder. "mod.rs is not required anymore" sounds better for me.

And lastly it shouldn't state "In Rust 2015..." / "In Rust 2018..." if it is not about edition anyore, but rather compiller version. Maybe something like ""In Rust 2015 (before 1.31)...".