diff --git a/src/items/modules.md b/src/items/modules.md index 3cc015025b..c4302be243 100644 --- a/src/items/modules.md +++ b/src/items/modules.md @@ -70,11 +70,34 @@ 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 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` 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 use of `path` on a module has effect. + +> [!NOTE] +> `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: