Skip to content

Commit fb674e9

Browse files
committed
Update use keyword docs to describe precise capturing
1 parent acfdb8d commit fb674e9

File tree

1 file changed

+37
-7
lines changed

1 file changed

+37
-7
lines changed

library/std/src/keyword_docs.rs

+37-7
Original file line numberDiff line numberDiff line change
@@ -2146,10 +2146,12 @@ mod unsafe_keyword {}
21462146

21472147
#[doc(keyword = "use")]
21482148
//
2149-
/// Import or rename items from other crates or modules.
2149+
/// Import or rename items from other crates or modules, or specify precise capturing with `use<..>`.
21502150
///
2151-
/// Usually a `use` keyword is used to shorten the path required to refer to a module item.
2152-
/// The keyword may appear in modules, blocks and even functions, usually at the top.
2151+
/// ## Importing Items
2152+
///
2153+
/// Usually, the `use` keyword is employed to shorten the path required to refer to a module item.
2154+
/// The keyword may appear in modules, blocks, and even functions, typically at the top.
21532155
///
21542156
/// The most basic usage of the keyword is `use path::to::item;`,
21552157
/// though a number of convenient shortcuts are supported:
@@ -2190,19 +2192,47 @@ mod unsafe_keyword {}
21902192
/// // Compiles.
21912193
/// let _ = VariantA;
21922194
///
2193-
/// // Does not compile !
2195+
/// // Does not compile!
21942196
/// let n = new();
21952197
/// ```
21962198
///
2197-
/// For more information on `use` and paths in general, see the [Reference].
2199+
/// For more information on `use` and paths in general, see the [Reference][reference1].
21982200
///
21992201
/// The differences about paths and the `use` keyword between the 2015 and 2018 editions
2200-
/// can also be found in the [Reference].
2202+
/// can also be found in the [Reference][reference1].
2203+
///
2204+
/// ## Precise Capturing Syntax
2205+
///
2206+
/// The `use<..>` syntax is used within certain `impl Trait` bounds to control which generic
2207+
/// parameters are captured. This is important for return-position `impl Trait` (RPIT) types,
2208+
/// as it affects borrow checking by influencing which generic parameters can be used in the
2209+
/// hidden type.
2210+
///
2211+
/// For example, the following function demonstrates an error without precise capturing:
2212+
///
2213+
/// ```rust,compile_fail,edition2021
2214+
/// fn f(x: &()) -> impl Sized { x }
2215+
/// ```
2216+
///
2217+
/// By using `use<'_>` for precise capturing, it can be resolved:
2218+
///
2219+
/// ```rust
2220+
/// fn f(x: &()) -> impl Sized + use<'_> { x }
2221+
/// ```
2222+
///
2223+
/// This syntax specifies that the lifetime of `x` should be captured and available in the
2224+
/// hidden type.
2225+
///
2226+
/// In Rust 2024, opaque types will automatically capture all lifetime parameters in scope.
2227+
/// `use<..>` syntax will serve as an important way of opting-out of that default.
2228+
///
2229+
/// For more details about precise capturing, see the [Reference][Reference2].
22012230
///
22022231
/// [`crate`]: keyword.crate.html
22032232
/// [`self`]: keyword.self.html
22042233
/// [`super`]: keyword.super.html
2205-
/// [Reference]: ../reference/items/use-declarations.html
2234+
/// [reference1]: ../reference/items/use-declarations.html
2235+
/// [reference2]: ../reference/types/impl-trait.html
22062236
mod use_keyword {}
22072237

22082238
#[doc(keyword = "where")]

0 commit comments

Comments
 (0)