From d1e3898bd5d830c29602067ffdb87639f99f0862 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Fri, 29 May 2020 23:41:46 +0200 Subject: [PATCH 1/3] Added the documentation for the 'use' keyword --- src/libstd/keyword_docs.rs | 58 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 6fbb0139b0eca..f74ee6a3e9b00 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -1213,9 +1213,63 @@ mod unsafe_keyword {} // /// Import or rename items from other crates or modules. /// -/// The documentation for this keyword is [not yet complete]. Pull requests welcome! +/// Usually a `use` keyword is used to shorten the path required to refer to a module item. +/// The keyword may appear in modules, blocks and even functions, usually at the top. +/// +/// The most basic usage of the keyword is `use path::to::item;`, +/// though a number of convenient shortcuts are supported: +/// +/// * Simultaneously binding a list of paths with a common prefix, +/// using the glob-like brace syntax use `a::b::{c, d, e::f, g::h::i};` +/// * Simultaneously binding a list of paths with a common prefix and their common parent module, +/// using the [`self`] keyword, such as `use a::b::{self, c, d::e};` +/// * Rebinding the target name as a new local name, using the syntax `use p::q::r as x;`. +/// This can also be used with the last two features: `use a::b::{self as ab, c as abc}`. +/// * Binding all paths matching a given prefix, +/// using the asterisk wildcard syntax `use a::b::*;`. +/// * Nesting groups of the previous features multiple times, +/// such as `use a::b::{self as ab, c, d::{*, e::f}};` +/// * Reexporting with visibility modifiers such as `pub use a::b;` +/// * Importing with `_` to only import the methods of the item without binding it to a name +/// (to avoid conflict for example): `use ::std::io::Read as _;`. +/// +/// Using path qualifiers like [`crate`], [`super`] or [`self`] is supported: `use crate::a::b;`. +/// +/// Note that when the wildcard `*` is used on a type, it does not import its methods (though +/// for `enum`s it imports the variants, as shown in the example below). +/// +/// ```compile_fail +/// # fn main() { +/// enum ExampleEnum { +/// VariantA, +/// VariantB, +/// } /// -/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601 +/// impl ExampleEnum { +/// fn new() -> Self { +/// Self::VariantA +/// } +/// } +/// +/// use ExampleEnum::*; +/// +/// // Compiles. +/// let _ = VariantA; +/// +/// // Does not compile ! +/// let n = new(); +/// # } +/// ``` +/// +/// For more information on `use` and paths in general, see the [Reference]. +/// +/// The differences about paths and the `use` keyword between the 2015 and 2018 editions +/// can also be found in the [Reference]. +/// +/// [`crate`]: keyword.crate.html +/// [`self`]: keyword.self.html +/// [`super`]: keyword.super.html +/// [Reference]: ../reference/items/use-declarations.html mod use_keyword {} #[doc(keyword = "where")] From b0e524d444ea1a060b248b7ffedd48693f14285b Mon Sep 17 00:00:00 2001 From: Poliorcetics Date: Sat, 30 May 2020 18:58:54 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Fix suggestions from review. Co-authored-by: Bastian Kauschke --- src/libstd/keyword_docs.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index f74ee6a3e9b00..a957bcf215f27 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -1220,7 +1220,7 @@ mod unsafe_keyword {} /// though a number of convenient shortcuts are supported: /// /// * Simultaneously binding a list of paths with a common prefix, -/// using the glob-like brace syntax use `a::b::{c, d, e::f, g::h::i};` +/// using the glob-like brace syntax `use a::b::{c, d, e::f, g::h::i};` /// * Simultaneously binding a list of paths with a common prefix and their common parent module, /// using the [`self`] keyword, such as `use a::b::{self, c, d::e};` /// * Rebinding the target name as a new local name, using the syntax `use p::q::r as x;`. @@ -1230,7 +1230,7 @@ mod unsafe_keyword {} /// * Nesting groups of the previous features multiple times, /// such as `use a::b::{self as ab, c, d::{*, e::f}};` /// * Reexporting with visibility modifiers such as `pub use a::b;` -/// * Importing with `_` to only import the methods of the item without binding it to a name +/// * Importing with `_` to only import the methods of a trait without binding it to a name /// (to avoid conflict for example): `use ::std::io::Read as _;`. /// /// Using path qualifiers like [`crate`], [`super`] or [`self`] is supported: `use crate::a::b;`. From 4bae9e59373e2ef405ea2601822137bd72122ef6 Mon Sep 17 00:00:00 2001 From: Poliorcetics Date: Sat, 30 May 2020 19:18:05 +0200 Subject: [PATCH 3/3] Remove the fn main() in code example --- src/libstd/keyword_docs.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index a957bcf215f27..a4996d9eee810 100644 --- a/src/libstd/keyword_docs.rs +++ b/src/libstd/keyword_docs.rs @@ -1238,8 +1238,7 @@ mod unsafe_keyword {} /// Note that when the wildcard `*` is used on a type, it does not import its methods (though /// for `enum`s it imports the variants, as shown in the example below). /// -/// ```compile_fail -/// # fn main() { +/// ```compile_fail,edition2018 /// enum ExampleEnum { /// VariantA, /// VariantB, @@ -1258,7 +1257,6 @@ mod unsafe_keyword {} /// /// // Does not compile ! /// let n = new(); -/// # } /// ``` /// /// For more information on `use` and paths in general, see the [Reference].