From f27684e63027086b1ec63ff97cf567e81dabec16 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sat, 21 Dec 2024 17:41:59 +0100 Subject: [PATCH 1/4] modules: describe both module filename styles without giving a clear preference --- src/items/modules.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/src/items/modules.md b/src/items/modules.md index 67322f845..887f2f89b 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -65,27 +65,22 @@ not have a `path` attribute, the path to the file mirrors the logical [module path]. r[items.mod.outlined.search] -Ancestor module path components are directories, and the module's -contents are in a file with the name of the module plus the `.rs` extension. +Ancestor module path components are directories, and the module's contents are in a file with the +name of the module plus the `.rs` extension. Alternatively, the module's contents can also be in a +file called `mod.rs` in a directory with the name of the module. It is not allowed to have both +`$name.rs` and `$name/mod.rs`. + For example, the following module structure can have this corresponding filesystem structure: Module Path | Filesystem Path | File Contents ------------------------- | --------------- | ------------- `crate` | `lib.rs` | `mod util;` -`crate::util` | `util.rs` | `mod config;` +`crate::util` | `util.rs` *or* `util/mod.rs` | `mod config;` `crate::util::config` | `util/config.rs` | -r[items.mod.outlined.search-mod] -Module filenames may also be the name of the module as a directory with the -contents in a file named `mod.rs` within that directory. The above example can -alternately be expressed with `crate::util`'s contents in a file named -`util/mod.rs`. It is not allowed to have both `util.rs` and `util/mod.rs`. - > **Note**: Prior to `rustc` 1.30, using `mod.rs` files was the way to load -> a module with nested children. It is encouraged to use the new naming -> convention as it is more consistent, and avoids having many files named -> `mod.rs` within a project. +> a module with nested children. ### The `path` attribute From 508d2db517954121335bf3bd4b077fad44d7aeb8 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 26 Feb 2025 17:35:15 +0100 Subject: [PATCH 2/4] add missing word Co-authored-by: Josh Triplett --- src/items/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/modules.md b/src/items/modules.md index 887f2f89b..e3b7d65a2 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -79,7 +79,7 @@ Module Path | Filesystem Path | File Contents `crate::util` | `util.rs` *or* `util/mod.rs` | `mod config;` `crate::util::config` | `util/config.rs` | -> **Note**: Prior to `rustc` 1.30, using `mod.rs` files was the way to load +> **Note**: Prior to `rustc` 1.30, using `mod.rs` files was the only way to load > a module with nested children. ### The `path` attribute From c8ad6595c7d3e4644b95edf70452eb569486717f Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 26 Feb 2025 18:44:07 +0100 Subject: [PATCH 3/4] mention 2018 rationale Co-authored-by: Josh Triplett --- src/items/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/modules.md b/src/items/modules.md index e3b7d65a2..9a3b20fc5 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -80,7 +80,7 @@ Module Path | Filesystem Path | File Contents `crate::util::config` | `util/config.rs` | > **Note**: Prior to `rustc` 1.30, using `mod.rs` files was the only way to load -> a module with nested children. +> a module with nested children. Rust 2018 added the new naming convention to be more consistent with modules that don't have submodules, and to avoid having many files named `mod.rs`. ### The `path` attribute From cad10dee8e44fdbe9fd8bc67f7c0d9ab256c83c6 Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Sun, 16 Mar 2025 22:32:16 +0100 Subject: [PATCH 4/4] make table exhaustive --- src/items/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/items/modules.md b/src/items/modules.md index 9a3b20fc5..033060009 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -77,7 +77,7 @@ Module Path | Filesystem Path | File Contents ------------------------- | --------------- | ------------- `crate` | `lib.rs` | `mod util;` `crate::util` | `util.rs` *or* `util/mod.rs` | `mod config;` -`crate::util::config` | `util/config.rs` | +`crate::util::config` | `util/config.rs` *or* `util/config/mod.rs` | > **Note**: Prior to `rustc` 1.30, using `mod.rs` files was the only way to load > a module with nested children. Rust 2018 added the new naming convention to be more consistent with modules that don't have submodules, and to avoid having many files named `mod.rs`.