From d1e3898bd5d830c29602067ffdb87639f99f0862 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Fri, 29 May 2020 23:41:46 +0200 Subject: Added the documentation for the 'use' keyword --- src/libstd/keyword_docs.rs | 58 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index 6fbb0139b0e..f74ee6a3e9b 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")] -- cgit 1.4.1-3-g733a5 From b0e524d444ea1a060b248b7ffedd48693f14285b Mon Sep 17 00:00:00 2001 From: Poliorcetics Date: Sat, 30 May 2020 18:58:54 +0200 Subject: 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(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index f74ee6a3e9b..a957bcf215f 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;`. -- cgit 1.4.1-3-g733a5 From 4bae9e59373e2ef405ea2601822137bd72122ef6 Mon Sep 17 00:00:00 2001 From: Poliorcetics Date: Sat, 30 May 2020 19:18:05 +0200 Subject: Remove the fn main() in code example --- src/libstd/keyword_docs.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs index a957bcf215f..a4996d9eee8 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]. -- cgit 1.4.1-3-g733a5 From 00a7b56bab317d9f1aaa5255145ce3414081cbfe Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Wed, 3 Jun 2020 23:32:26 +0200 Subject: Added the documentation about length to CString::from_raw --- src/libstd/ffi/c_str.rs | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs index 4bac9a4917d..3d7ac724fbd 100644 --- a/src/libstd/ffi/c_str.rs +++ b/src/libstd/ffi/c_str.rs @@ -395,6 +395,12 @@ impl CString { /// ownership of a string that was allocated by foreign code) is likely to lead /// to undefined behavior or allocator corruption. /// + /// It should be noted that the length isn't just "recomputed," but that + /// the recomputed length must match the original length from the + /// [`into_raw`] call. This means the [`into_raw`]/`from_raw` methods + /// should not be used when passing the string to C functions that can + /// modify the string's length. + /// /// > **Note:** If you need to borrow a string that was allocated by /// > foreign code, use [`CStr`]. If you need to take ownership of /// > a string that was allocated by foreign code, you will need to -- cgit 1.4.1-3-g733a5 From 87abe174c46bf10246369e63a36eccd6748b7dbe Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Wed, 3 Jun 2020 23:55:41 +0200 Subject: Added a warning to CString::into_raw too --- src/libstd/ffi/c_str.rs | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/ffi/c_str.rs b/src/libstd/ffi/c_str.rs index 3d7ac724fbd..b324b161896 100644 --- a/src/libstd/ffi/c_str.rs +++ b/src/libstd/ffi/c_str.rs @@ -446,6 +446,11 @@ impl CString { /// /// Failure to call [`from_raw`] will lead to a memory leak. /// + /// The C side must **not** modify the length of the string (by writing a + /// `NULL` somewhere inside the string or removing the final one) before + /// it makes it back into Rust using [`from_raw`]. See the safety section + /// in [`from_raw`]. + /// /// [`from_raw`]: #method.from_raw /// /// # Examples -- cgit 1.4.1-3-g733a5