From 4e8d720d7e64d308d4f6f79686b2709f1700bc8e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 23 Jun 2025 15:17:29 -0700 Subject: [PATCH 1/2] Update `path` to use the attribute template --- src/items/modules.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/src/items/modules.md b/src/items/modules.md index 3cc015025b..e113ac82a5 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -74,7 +74,29 @@ r[items.mod.outlined.path] ### The `path` attribute r[items.mod.outlined.path.intro] -The directories and files used for loading external file modules can be influenced with the `path` attribute. +The *`path` [attribute][attributes]* specifies the file to load for a module. + +> [!EXAMPLE] +> +> ```rust,ignore +> #[path = "other_file.rs"] +> pub mod example; +> ``` + +r[items.mod.outlined.path.syntax] +The `path` attribute uses the [MetaNameValueStr] syntax to specify the path to the file. + +r[items.mod.outlined.path.allowed-positions] +The `path` attribute may only be applied to module declarations. + +> [!NOTE] +> `rustc` currently warns in other positions, but this may be rejected in the future. + +r[items.mod.outlined.path.duplicates] +Only the first instance of `path` on a module is honored. Subsequent `path` attributes are ignored. + +> [!NOTE] +> `rustc` currently warns on following duplicate `path` attributes. This may become an error in the future. r[items.mod.outlined.path.search] For `path` attributes on modules not inside inline module blocks, the file path is relative to the directory the source file is located. For example, the following code snippet would use the paths shown based on where it is located: From 23c2e1f671282d4e7098a4a10c92a5919241dfe0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 7 Oct 2025 14:00:56 -0700 Subject: [PATCH 2/2] Update path for updated attribute template --- src/items/modules.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/items/modules.md b/src/items/modules.md index e113ac82a5..c4302be243 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -70,6 +70,7 @@ Module filenames may also be the name of the module as a directory with the cont > [!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. + r[items.mod.outlined.path] ### The `path` attribute @@ -90,13 +91,13 @@ r[items.mod.outlined.path.allowed-positions] The `path` attribute may only be applied to module declarations. > [!NOTE] -> `rustc` currently warns in other positions, but this may be rejected in the future. +> `rustc` ignores use in other positions but lints against it. This may become an error in the future. r[items.mod.outlined.path.duplicates] -Only the first instance of `path` on a module is honored. Subsequent `path` attributes are ignored. +Only the first use of `path` on a module has effect. > [!NOTE] -> `rustc` currently warns on following duplicate `path` attributes. This may become an error in the future. +> `rustc` lints against any use following the first. This may become an error in the future. r[items.mod.outlined.path.search] For `path` attributes on modules not inside inline module blocks, the file path is relative to the directory the source file is located. For example, the following code snippet would use the paths shown based on where it is located: