From 947c10758c3ee7450ea904b1de76aa8b42f4bec7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:09:27 -0800 Subject: [PATCH 1/8] Remove bullet list from use restrictions As with other parts of the reference, the structure is moving more towards a set of rules, and the bullet list here isn't necessary. --- src/items/use-declarations.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 5ea891cef2..9c41dbd75c 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -367,31 +367,33 @@ m!(use std as _;); r[items.use.restrictions] ## Restrictions -The following are restrictions for valid `use` declarations: +The following rules are restrictions for valid `use` declarations. r[items.use.restrictions.crate] -* `use crate;` must use `as` to define the name to which to bind the crate root. +`use crate;` must use `as` to define the name to which to bind the crate root. r[items.use.restrictions.self] -* `use {self};` is an error; there must be a leading segment when using `self`. +`use {self};` is an error; there must be a leading segment when using `self`. r[items.use.restrictions.duplicate-name] -* As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. +As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. r[items.use.restrictions.macro-crate] -* `use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. +`use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. r[items.use.restrictions.variant] -* `use` paths cannot refer to enum variants through a [type alias]. For example: - ```rust,compile_fail - enum MyEnum { - MyVariant - } - type TypeAlias = MyEnum; - - use MyEnum::MyVariant; //~ OK - use TypeAlias::MyVariant; //~ ERROR - ``` +`use` paths cannot refer to enum variants through a [type alias]. + +> [!EXAMPLE] +> ```rust,compile_fail +> enum MyEnum { +> MyVariant +> } +> type TypeAlias = MyEnum; +> +> use MyEnum::MyVariant; //~ OK +> use TypeAlias::MyVariant; //~ ERROR +> ``` [Attributes]: ../attributes.md [Built-in types]: ../types.md From 8b4481b5879bd9007ac17d74aa8f86ab18283645 Mon Sep 17 00:00:00 2001 From: mu001999 Date: Fri, 16 Jan 2026 23:00:48 +0800 Subject: [PATCH 2/8] Document importing path-segment keyword --- src/items/use-declarations.md | 71 +++++++++++++++++++++++++++++++++-- 1 file changed, 68 insertions(+), 3 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 9c41dbd75c..94f7720cfe 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -193,6 +193,22 @@ Braces can be nested, creating a tree of paths, where each grouping of segments use std::collections::{BTreeSet, hash_map::{self, HashMap}}; ``` +Braces may also import `self` from the current scope when it is explicitly renamed: + +```rust +mod m { + pub fn f() {} + + use {f as local_f, self as this_module}; + + pub fn g() { + local_f(); + this_module::f(); + } +} +# fn main() {} +``` + r[items.use.multiple-syntax.empty] An empty brace does not import anything, though the leading path is validated that it is accessible. @@ -370,16 +386,65 @@ r[items.use.restrictions] The following rules are restrictions for valid `use` declarations. r[items.use.restrictions.crate] -`use crate;` must use `as` to define the name to which to bind the crate root. +Importing the crate root (`crate`) must use `as` to define the name to which to bind it. + +> [!EXAMPLE] +> ```rust +> use crate as root; +> use crate::{self as root2}; +> +> // Not allowed: +> // use crate; +> // use crate::{self}; +> ``` r[items.use.restrictions.self] -`use {self};` is an error; there must be a leading segment when using `self`. +Importing `self` as an entity must use `as` to define the binding name (this does not affect `self` used within a prefixed brace import like `use a::b::{self, c};`). + +> [!EXAMPLE] +> ```rust +> use {self as this_module}; +> use self as this_module2; +> use self::{self as this_module3}; +> +> // Not allowed: +> // use {self}; +> // use self; +> // use self::{self}; +> ``` + +r[items.use.restrictions.super] +Importing `super` (including repeated `super::super`) as an entity must use `as` to define the binding name (this does not affect importing items from ancestors like `use super::item;`). + +> [!EXAMPLE] +> ```rust +> use super as parent; +> use super::{self as parent2}; +> use super::super as grandparent; +> use super::super::{self as grandparent2}; +> +> // Not allowed: +> // use super; +> // use super::{self}; +> // use super::super; +> // use super::super::{self}; +> ``` r[items.use.restrictions.duplicate-name] As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. r[items.use.restrictions.macro-crate] -`use` paths with `$crate` are not allowed in a [`macro_rules`] expansion. +Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity must use `as` to define the binding name. + +> [!EXAMPLE] +> ```rust +> macro_rules! import_crate_root { +> () => { +> use $crate as my_crate; +> use $crate::{self as my_crate2}; +> }; +> } +> ``` r[items.use.restrictions.variant] `use` paths cannot refer to enum variants through a [type alias]. From e95a59261e080fd7b3e767e4433f028c3267d89f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:13:12 -0800 Subject: [PATCH 3/8] Move `self` note This note was more of a general commentary on `self`, and was not specifically attached to its previous rule of items.use.self.namespace. --- src/items/use-declarations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 94f7720cfe..3188503104 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -239,6 +239,9 @@ mod example { # fn main() {} ``` +> [!NOTE] +> `self` may also be used as the first segment of a path. The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. See [`self`] in the paths chapter for more information on the meaning of a leading `self`. + r[items.use.self.namespace] `self` only creates a binding from the [type namespace] of the parent entity. For example, in the following, only the `foo` mod is imported: @@ -258,9 +261,6 @@ fn main() { } ``` -> [!NOTE] -> `self` may also be used as the first segment of a path. The usage of `self` as the first segment and inside a `use` brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. See [`self`] in the paths chapter for more information on the meaning of a leading `self`. - r[items.use.glob] ## Glob imports From 376cbde4670f6aa1efa13d6aefedd81c9914c77d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:21:34 -0800 Subject: [PATCH 4/8] Remove this statement about `self` in braces This is somewhat duplicated with the `self` section and the restrictions section which already describes about renaming. --- src/items/use-declarations.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 3188503104..4018d08ac2 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -193,22 +193,6 @@ Braces can be nested, creating a tree of paths, where each grouping of segments use std::collections::{BTreeSet, hash_map::{self, HashMap}}; ``` -Braces may also import `self` from the current scope when it is explicitly renamed: - -```rust -mod m { - pub fn f() {} - - use {f as local_f, self as this_module}; - - pub fn g() { - local_f(); - this_module::f(); - } -} -# fn main() {} -``` - r[items.use.multiple-syntax.empty] An empty brace does not import anything, though the leading path is validated that it is accessible. From e6f28649d97ce9f5caa571ebba376d7dd757b259 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 09:22:36 -0800 Subject: [PATCH 5/8] Move items.use.restrictions.macro-crate This moves `$crate` to be next to `crate` since they are closely related. --- src/items/use-declarations.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 4018d08ac2..511ca03915 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -382,6 +382,19 @@ Importing the crate root (`crate`) must use `as` to define the name to which to > // use crate::{self}; > ``` +r[items.use.restrictions.macro-crate] +Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity must use `as` to define the binding name. + +> [!EXAMPLE] +> ```rust +> macro_rules! import_crate_root { +> () => { +> use $crate as my_crate; +> use $crate::{self as my_crate2}; +> }; +> } +> ``` + r[items.use.restrictions.self] Importing `self` as an entity must use `as` to define the binding name (this does not affect `self` used within a prefixed brace import like `use a::b::{self, c};`). @@ -417,19 +430,6 @@ Importing `super` (including repeated `super::super`) as an entity must use `as` r[items.use.restrictions.duplicate-name] As with any item definition, `use` imports cannot create duplicate bindings of the same name in the same namespace in a module or block. -r[items.use.restrictions.macro-crate] -Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity must use `as` to define the binding name. - -> [!EXAMPLE] -> ```rust -> macro_rules! import_crate_root { -> () => { -> use $crate as my_crate; -> use $crate::{self as my_crate2}; -> }; -> } -> ``` - r[items.use.restrictions.variant] `use` paths cannot refer to enum variants through a [type alias]. From 588972ad3c9754cbe58497eef8a1ceebd6cd0cca Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 10:45:11 -0800 Subject: [PATCH 6/8] Tweak wording for `use` restrictions This tries to simplify the wording and to maintain consistency, since they are all essentially saying the same thing. --- src/items/use-declarations.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index 511ca03915..e23c325c3b 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -369,8 +369,8 @@ r[items.use.restrictions] The following rules are restrictions for valid `use` declarations. -r[items.use.restrictions.crate] -Importing the crate root (`crate`) must use `as` to define the name to which to bind it. +r[items.use.restrictions.crate-alias] +When using `crate` to import the current crate, you must use `as` to define the binding name. > [!EXAMPLE] > ```rust @@ -382,8 +382,8 @@ Importing the crate root (`crate`) must use `as` to define the name to which to > // use crate::{self}; > ``` -r[items.use.restrictions.macro-crate] -Within a macro transcriber, `$crate` may be used in `use` paths as the first segment (see `$crate` in the paths chapter). Importing `$crate` as an entity must use `as` to define the binding name. +r[items.use.restrictions.macro-crate-alias] +When using [`$crate`] in a macro transcriber to import the current crate, you must use `as` to define the binding name. > [!EXAMPLE] > ```rust @@ -395,8 +395,8 @@ Within a macro transcriber, `$crate` may be used in `use` paths as the first seg > } > ``` -r[items.use.restrictions.self] -Importing `self` as an entity must use `as` to define the binding name (this does not affect `self` used within a prefixed brace import like `use a::b::{self, c};`). +r[items.use.restrictions.self-alias] +When using `self` to import the current module, you must use `as` to define the binding name. > [!EXAMPLE] > ```rust @@ -410,8 +410,8 @@ Importing `self` as an entity must use `as` to define the binding name (this doe > // use self::{self}; > ``` -r[items.use.restrictions.super] -Importing `super` (including repeated `super::super`) as an entity must use `as` to define the binding name (this does not affect importing items from ancestors like `use super::item;`). +r[items.use.restrictions.super-alias] +When using `super` to import a parent module, you must use `as` to define the binding name. > [!EXAMPLE] > ```rust @@ -444,6 +444,7 @@ r[items.use.restrictions.variant] > use TypeAlias::MyVariant; //~ ERROR > ``` +[`$crate`]: paths.qualifiers.macro-crate [Attributes]: ../attributes.md [Built-in types]: ../types.md [Derive macros]: macro.proc.derive From ee2c25b6a0a29c3e8ae642365616e1e39ea251db Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 10:47:14 -0800 Subject: [PATCH 7/8] Add a note in paths that `use` paths have differences The rules in the paths chapter don't entirely reflect what a valid path in a `use` declaration is. I'm not entirely sure what's the best approach for describing how paths work since there are several differences between `use` paths and expression paths. --- src/paths.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/paths.md b/src/paths.md index d28877d2a5..0c80ff2f4a 100644 --- a/src/paths.md +++ b/src/paths.md @@ -188,6 +188,9 @@ r[paths.qualifiers] Paths can be denoted with various leading qualifiers to change the meaning of how it is resolved. +> [!NOTE] +> [`use` declarations] have additional behaviors and restrictions for `self`, `super`, `crate`, and `$crate`. + r[paths.qualifiers.global-root] ### `::` @@ -486,5 +489,6 @@ mod without { // crate::without [traits]: items/traits.md [types]: types.md [union]: items/unions.md +[`use` declarations]: items/use-declarations.md [value namespace]: names/namespaces.md [visibility]: visibility-and-privacy.md From ef94e6a651b27439afc2e507b4c85447c38771c2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 25 Jan 2026 11:00:09 -0800 Subject: [PATCH 8/8] Fix broken example --- src/items/use-declarations.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md index e23c325c3b..513ded7019 100644 --- a/src/items/use-declarations.md +++ b/src/items/use-declarations.md @@ -415,16 +415,20 @@ When using `super` to import a parent module, you must use `as` to define the bi > [!EXAMPLE] > ```rust -> use super as parent; -> use super::{self as parent2}; -> use super::super as grandparent; -> use super::super::{self as grandparent2}; +> mod a { +> mod b { +> use super as parent; +> use super::{self as parent2}; +> use super::super as grandparent; +> use super::super::{self as grandparent2}; > -> // Not allowed: -> // use super; -> // use super::{self}; -> // use super::super; -> // use super::super::{self}; +> // Not allowed: +> // use super; +> // use super::{self}; +> // use super::super; +> // use super::super::{self}; +> } +> } > ``` r[items.use.restrictions.duplicate-name]