Skip to content

Update path to use the attribute template #1915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update path to use the attribute template #1915

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9231b58
Unwrap path
ehuss Jun 23, 2025
57e3a82
Update `path` to use the attribute template
ehuss Jun 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 26 additions & 17 deletions src/items/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,13 +88,32 @@ 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]
> <!-- ignore: requires external files -->
> ```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:
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:

<!-- ignore: requires external files -->
```rust,ignore
Expand All @@ -108,16 +127,7 @@ Source File | `c`'s File Location | `c`'s Module Path
`src/a/mod.rs` | `src/a/foo.rs` | `crate::a::c`

r[items.mod.outlined.path.search-nested]
For `path` attributes inside inline module blocks, the relative location of
the file path depends on the kind of source file the `path` attribute is
located in. "mod-rs" source files are root modules (such as `lib.rs` or
`main.rs`) and modules with files named `mod.rs`. "non-mod-rs" source files
are all other module files. Paths for `path` attributes inside inline module
blocks in a mod-rs file are relative to the directory of the mod-rs file
including the inline module components as directories. For non-mod-rs files,
it is the same except the path starts with a directory with the name of the
non-mod-rs module. For example, the following code snippet would use the paths
shown based on where it is located:
For `path` attributes inside inline module blocks, the relative location of the file path depends on the kind of source file the `path` attribute is located in. "mod-rs" source files are root modules (such as `lib.rs` or `main.rs`) and modules with files named `mod.rs`. "non-mod-rs" source files are all other module files. Paths for `path` attributes inside inline module blocks in a mod-rs file are relative to the directory of the mod-rs file including the inline module components as directories. For non-mod-rs files, it is the same except the path starts with a directory with the name of the non-mod-rs module. For example, the following code snippet would use the paths shown based on where it is located:

<!-- ignore: requires external files -->
```rust,ignore
Expand All @@ -132,8 +142,7 @@ Source File | `inner`'s File Location | `inner`'s Module Path
`src/a/b.rs` | `src/a/b/inline/other.rs` | `crate::a::b::inline::inner`
`src/a/mod.rs` | `src/a/inline/other.rs` | `crate::a::inline::inner`

An example of combining the above rules of `path` attributes on inline modules
and nested modules within (applies to both mod-rs and non-mod-rs files):
An example of combining the above rules of `path` attributes on inline modules and nested modules within (applies to both mod-rs and non-mod-rs files):

<!-- ignore: requires external files -->
```rust,ignore
Expand Down