Update `use` keyword docs to describe precise capturing · qinheping/verify-rust-std@ff3f33f (original) (raw)

`@@ -2146,10 +2146,13 @@ mod unsafe_keyword {}

2146

2147

`#[doc(keyword = "use")]

2148

`//

2149

/// Import or rename items from other crates or modules.

2149

/// Import or rename items from other crates or modules, or specify precise capturing

2150

`` +

/// with use<..>.

2150

2151

`///

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.

2152

/// ## Importing items

2153

///

2154

`` +

/// The use keyword is employed to shorten the path required to refer to a module item.

2155

/// The keyword may appear in modules, blocks, and even functions, typically at the top.

2153

2156

`///

2154

2157

`` /// The most basic usage of the keyword is use path::to::item;,

2155

2158

`/// though a number of convenient shortcuts are supported:

`@@ -2190,19 +2193,48 @@ mod unsafe_keyword {}

2190

2193

`/// // Compiles.

2191

2194

`/// let _ = VariantA;

2192

2195

`///

2193

/// // Does not compile !

2196

/// // Does not compile!

2194

2197

`/// let n = new();

2195

2198

```` /// ```


`2196`

`2199`

`///

`

`2197`

``

`` -

/// For more information on `use` and paths in general, see the [Reference].

``

``

`2200`

`` +

/// For more information on `use` and paths in general, see the [Reference][ref-use-decls].

``

`2198`

`2201`

`///

`

`2199`

`2202`

`` /// The differences about paths and the `use` keyword between the 2015 and 2018 editions

``

`2200`

``

`-

/// can also be found in the [Reference].

`

``

`2203`

`+

/// can also be found in the [Reference][ref-use-decls].

`

``

`2204`

`+

///

`

``

`2205`

`+

/// ## Precise capturing

`

``

`2206`

`+

///

`

``

`2207`

`` +

/// The `use<..>` syntax is used within certain `impl Trait` bounds to control which generic

``

``

`2208`

`` +

/// parameters are captured. This is important for return-position `impl Trait` (RPIT) types,

``

``

`2209`

`+

/// as it affects borrow checking by controlling which generic parameters can be used in the

`

``

`2210`

`+

/// hidden type.

`

``

`2211`

`+

///

`

``

`2212`

`+

/// For example, the following function demonstrates an error without precise capturing in

`

``

`2213`

`+

/// Rust 2021 and earlier editions:

`

``

`2214`

`+

///

`

``

`2215`

```` +

/// ```rust,compile_fail,edition2021

2216

/// fn f(x: &()) -> impl Sized { x }

2217


/// ```

2218

///

2219

`` +

/// By using use<'_> for precise capturing, it can be resolved:

2220

///

2221


/// ```rust

2222

/// fn f(x: &()) -> impl Sized + use<'_> { x }

2223


/// ```

2224

///

2225

/// This syntax specifies that the elided lifetime be captured and therefore available for

2226

/// use in the hidden type.

2227

///

2228

/// In Rust 2024, opaque types automatically capture all lifetime parameters in scope.

2229

`` +

/// use<..> syntax serves as an important way of opting-out of that default.

2230

///

2231

/// For more details about precise capturing, see the [Reference][ref-impl-trait].

2201

2232

`///

2202

2233

`` /// [crate]: keyword.crate.html

2203

2234

`` /// [self]: keyword.self.html

2204

2235

`` /// [super]: keyword.super.html

2205

/// [Reference]: ../reference/items/use-declarations.html

2236

/// [ref-use-decls]: ../reference/items/use-declarations.html

2237

/// [ref-impl-trait]: ../reference/types/impl-trait.html

2206

2238

`mod use_keyword {}

2207

2239

2208

2240

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

Update use keyword docs to describe precise capturing · qinheping/verify-rust-std@ff3f33f (original) (raw)

Update `use` keyword docs to describe precise capturing · qinheping/verify-rust-std@ff3f33f (original) (raw)