From bde6336976f9a660fb9b14b89316ade85837fe44 Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Fri, 24 Mar 2017 23:29:23 -0400 Subject: [PATCH 1/8] Update `Child` docs to not have a note section In #29370 it's noted that for "the Note shouldn't be one, and should come before the examples." This commit changes the positioning of the section and removes wording that said take note in order for it to flow better with the surrounding text and it's new position. --- src/libstd/process.rs | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7a85e58866236..293c8501400a4 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -73,6 +73,15 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// spawning process and can itself be constructed using a builder-style /// interface. /// +/// There is no implementation of [`Drop`] for child processes, +/// so if you do not ensure the `Child` has exited then it will continue to +/// run, even after the `Child` handle to the child process has gone out of +/// scope. +/// +/// Calling [`wait`][`wait`] (or other functions that wrap around it) will make +/// the parent process wait until the child has actually exited before +/// continuing. +/// /// # Examples /// /// ```should_panic @@ -89,17 +98,6 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// assert!(ecode.success()); /// ``` /// -/// # Note -/// -/// Take note that there is no implementation of [`Drop`] for child processes, -/// so if you do not ensure the `Child` has exited then it will continue to -/// run, even after the `Child` handle to the child process has gone out of -/// scope. -/// -/// Calling [`wait`][`wait`] (or other functions that wrap around it) will make -/// the parent process wait until the child has actually exited before -/// continuing. -/// /// [`Command`]: struct.Command.html /// [`Drop`]: ../../core/ops/trait.Drop.html /// [`wait`]: #method.wait From 7ef1b39b2525dc5475f86b6dc27aa60fe5b3fdca Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Sat, 25 Mar 2017 16:16:50 -0400 Subject: [PATCH 2/8] Remove extra wait from Child docs --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 293c8501400a4..edcf206501a08 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -78,7 +78,7 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// run, even after the `Child` handle to the child process has gone out of /// scope. /// -/// Calling [`wait`][`wait`] (or other functions that wrap around it) will make +/// Calling [`wait`] (or other functions that wrap around it) will make /// the parent process wait until the child has actually exited before /// continuing. /// From 7897e168bdd9708f83514a9c3e88d83278de4334 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Sat, 1 Apr 2017 15:35:03 +1100 Subject: [PATCH 3/8] Convert docs clean up. --- src/libcore/convert.rs | 145 ++++++++++++++++++++++++++++++++--------- 1 file changed, 114 insertions(+), 31 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 0b0f831f093b0..5546d2a13c478 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -17,8 +17,8 @@ //! Like many traits, these are often used as bounds for generic functions, to //! support arguments of multiple types. //! -//! - Impl the `As*` traits for reference-to-reference conversions -//! - Impl the [`Into`] trait when you want to consume the value in the conversion +//! - Implement the `As*` traits for reference-to-reference conversions +//! - Implement the [`Into`] trait when you want to consume the value in the conversion //! - The [`From`] trait is the most flexible, useful for value _and_ reference conversions //! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], but allow for the //! conversion to fail @@ -29,7 +29,7 @@ //! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a blanket implementation //! in the standard library. //! -//! # Generic impl +//! # Generic Implementations //! //! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference //! - [`From`]` for T` implies [`Into`]` for U` @@ -50,10 +50,20 @@ use str::FromStr; -/// A cheap, reference-to-reference conversion. +/// A cheap reference-to-reference conversion. Used to convert a value to a reference value +/// within generic code. /// -/// `AsRef` is very similar to, but different than, [`Borrow`]. See -/// [the book][book] for more. +/// `AsRef` is very similar to, but serves a slightly different purpose than, [`Borrow`]. +/// +/// `AsRef` is to be used when wishing to convert to a reference of another type. +/// `Borrow` is more related to the notion of taking the reference. It is useful when wishing to abstract +/// over the type of reference (`&T`, `&mut T`) or allow both the referenced and owned type to be treated in the same manner. +/// The key difference between the two traits is the intention: +/// +/// - Use `AsRef` when goal is to simply convert into a reference +/// - Use `Borrow` when goal is related to writing code that is agnostic to the type of borrow and if is reference or value +/// +/// See [the book][book] for a more detailed comparison. /// /// [book]: ../../book/borrow-and-asref.html /// [`Borrow`]: ../../std/borrow/trait.Borrow.html @@ -64,7 +74,23 @@ use str::FromStr; /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html /// +/// # Generic Implementations +/// +/// - `AsRef` auto-dereferences if the inner type is a reference or a mutable +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// /// # Examples +/// An example implementation of the trait is [`Path`]. +/// +/// [`Path`]: ../../std/struct.Path.html +/// +/// ``` +/// impl AsRef for str { +/// fn as_ref(&self) -> &Path { +/// Path::new(self) +/// } +/// } +/// ``` /// /// Both [`String`] and `&str` implement `AsRef`: /// @@ -82,11 +108,6 @@ use str::FromStr; /// is_hello(s); /// ``` /// -/// # Generic Impls -/// -/// - `AsRef` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) -/// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsRef { /// Performs the conversion. @@ -96,12 +117,19 @@ pub trait AsRef { /// A cheap, mutable reference-to-mutable reference conversion. /// +/// This trait is similar to `AsRef` but used for converting mutable references. +/// /// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which /// returns an [`Option`] or a [`Result`]. /// /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html /// +/// # Generic Implementations +/// +/// - `AsMut` auto-dereferences if the inner type is a reference or a mutable +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// /// # Examples /// /// [`Box`] implements `AsMut`: @@ -118,10 +146,13 @@ pub trait AsRef { /// assert_eq!(*boxed_num, 1); /// ``` /// -/// # Generic Impls +/// Implementing `AsMut`: /// -/// - `AsMut` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// ``` +/// impl Type { +/// let a = 1; +/// } +/// ``` /// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut { @@ -130,7 +161,7 @@ pub trait AsMut { fn as_mut(&mut self) -> &mut T; } -/// A conversion that consumes `self`, which may or may not be expensive. +/// A conversion that consumes `self`, which may or may not be expensive. The reciprocal of [`From`][From]. /// /// **Note: this trait must not fail**. If the conversion can fail, use [`TryInto`] or a dedicated /// method which returns an [`Option`] or a [`Result`]. @@ -139,6 +170,11 @@ pub trait AsMut { /// the [`From`][From] trait, which offers greater flexibility and provides an equivalent `Into` /// implementation for free, thanks to a blanket implementation in the standard library. /// +/// # Generic Implementations +/// +/// - [`From`][From]` for U` implies `Into for T` +/// - [`into`] is reflexive, which means that `Into for T` is implemented +/// /// # Examples /// /// [`String`] implements `Into>`: @@ -153,11 +189,6 @@ pub trait AsMut { /// is_hello(s); /// ``` /// -/// # Generic Impls -/// -/// - [`From`][From]` for U` implies `Into for T` -/// - [`into`] is reflexive, which means that `Into for T` is implemented -/// /// [`TryInto`]: trait.TryInto.html /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html @@ -171,11 +202,24 @@ pub trait Into: Sized { fn into(self) -> T; } -/// Construct `Self` via a conversion. +/// Simple and safe type conversions in to `Self`. It is the reciprocal of `Into`. +/// +/// This trait is useful when performing error handling as described by [the book][book] and is closely related to the `?` operator. +/// +/// When constructing a function that is capable of failing the return type will generally be of the form `Result`. +/// The `From` trait allows for simplification of error handling by providing a means of returning a single error type that encapsulates +/// numerous possible erroneous situations. +/// This trait is not limited to error handling, rather the general case for this trait would be in any type conversions to have an +/// explicit definition of how they are performed. /// /// **Note: this trait must not fail**. If the conversion can fail, use [`TryFrom`] or a dedicated /// method which returns an [`Option`] or a [`Result`]. /// +/// # Generic Implementations +/// +/// - `From for U` implies [`Into`]` for T` +/// - [`from`] is reflexive, which means that `From for T` is implemented +/// /// # Examples /// /// [`String`] implements `From<&str>`: @@ -186,10 +230,34 @@ pub trait Into: Sized { /// /// assert_eq!(string, other_string); /// ``` -/// # Generic impls /// -/// - `From for U` implies [`Into`]` for T` -/// - [`from`] is reflexive, which means that `From for T` is implemented +/// An example usage for error handling: +/// +/// ``` +/// enum CliError { +/// IoError(io::Error), +/// ParseError(num::ParseIntError), +/// } +/// +/// impl From for MyError { +/// fn from(error: io::Error) -> Self { +/// CliError::IoError(error) +/// } +/// } +/// +/// impl From for MyError { +/// fn from(error: io::Error) -> Self { +/// CliError::ParseError(error) +/// } +/// } +/// +/// fn open_and_parse_file(file_name: &str) -> Result { +/// let file = std::fs::File::open("test")?; +/// let mut contents = String::new(); +/// file.read_to_string(&mut contents)?; +/// let num: i32 = contents.trim().parse()?; +/// } +/// ``` /// /// [`TryFrom`]: trait.TryFrom.html /// [`Option`]: ../../std/option/enum.Option.html @@ -197,6 +265,7 @@ pub trait Into: Sized { /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html /// [`from`]: trait.From.html#tymethod.from +/// [book]: ../../book/error-handling.html#the-from-trait #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. @@ -236,7 +305,9 @@ pub trait TryFrom: Sized { // As lifts over & #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T where T: AsRef { +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T + where T: AsRef +{ fn as_ref(&self) -> &U { >::as_ref(*self) } @@ -244,7 +315,9 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T where T: AsRef { // As lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T where T: AsRef { +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T + where T: AsRef +{ fn as_ref(&self) -> &U { >::as_ref(*self) } @@ -260,7 +333,9 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T where T: AsRef { // AsMut lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T where T: AsMut { +impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T + where T: AsMut +{ fn as_mut(&mut self) -> &mut U { (*self).as_mut() } @@ -276,7 +351,9 @@ impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T where T: AsMut { // From implies Into #[stable(feature = "rust1", since = "1.0.0")] -impl Into for T where U: From { +impl Into for T + where U: From +{ fn into(self) -> U { U::from(self) } @@ -285,13 +362,17 @@ impl Into for T where U: From { // From (and thus Into) is reflexive #[stable(feature = "rust1", since = "1.0.0")] impl From for T { - fn from(t: T) -> T { t } + fn from(t: T) -> T { + t + } } // TryFrom implies TryInto #[unstable(feature = "try_from", issue = "33417")] -impl TryInto for T where U: TryFrom { +impl TryInto for T + where U: TryFrom +{ type Error = U::Error; fn try_into(self) -> Result { @@ -327,7 +408,9 @@ impl AsRef for str { // FromStr implies TryFrom<&str> #[unstable(feature = "try_from", issue = "33417")] -impl<'a, T> TryFrom<&'a str> for T where T: FromStr { +impl<'a, T> TryFrom<&'a str> for T + where T: FromStr +{ type Error = ::Err; fn try_from(s: &'a str) -> Result { From 79efca10934b3ea0a172db0ab514fdd72ddeacfb Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Mon, 3 Apr 2017 07:57:20 +1000 Subject: [PATCH 4/8] Wrapped to 80 characters. Fix links. --- src/libcore/convert.rs | 98 +++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 40 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 5546d2a13c478..19cd2d3398f39 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -26,16 +26,16 @@ //! As a library author, you should prefer implementing [`From`][`From`] or //! [`TryFrom`][`TryFrom`] rather than [`Into`][`Into`] or [`TryInto`][`TryInto`], //! as [`From`] and [`TryFrom`] provide greater flexibility and offer -//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a blanket implementation -//! in the standard library. +//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a +//! blanket implementation in the standard library. //! //! # Generic Implementations //! //! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference //! - [`From`]` for T` implies [`Into`]` for U` //! - [`TryFrom`]` for T` implies [`TryInto`]` for U` -//! - [`From`] and [`Into`] are reflexive, which means that all types can `into()` -//! themselves and `from()` themselves +//! - [`From`] and [`Into`] are reflexive, which means that all types can +//! `into()` themselves and `from()` themselves //! //! See each trait for usage examples. //! @@ -50,26 +50,31 @@ use str::FromStr; -/// A cheap reference-to-reference conversion. Used to convert a value to a reference value -/// within generic code. -/// -/// `AsRef` is very similar to, but serves a slightly different purpose than, [`Borrow`]. -/// -/// `AsRef` is to be used when wishing to convert to a reference of another type. -/// `Borrow` is more related to the notion of taking the reference. It is useful when wishing to abstract -/// over the type of reference (`&T`, `&mut T`) or allow both the referenced and owned type to be treated in the same manner. +/// A cheap reference-to-reference conversion. Used to convert a value to a +/// reference value within generic code. +/// +/// `AsRef` is very similar to, but serves a slightly different purpose than, +/// [`Borrow`]. +/// +/// `AsRef` is to be used when wishing to convert to a reference of another +/// type. +/// `Borrow` is more related to the notion of taking the reference. It is +/// useful when wishing to abstract +/// over the type of reference (`&T`, `&mut T`) or allow both the referenced +/// and owned type to be treated in the same manner. /// The key difference between the two traits is the intention: /// /// - Use `AsRef` when goal is to simply convert into a reference -/// - Use `Borrow` when goal is related to writing code that is agnostic to the type of borrow and if is reference or value +/// - Use `Borrow` when goal is related to writing code that is agnostic to the +/// type of borrow and if is reference or value /// /// See [the book][book] for a more detailed comparison. /// /// [book]: ../../book/borrow-and-asref.html /// [`Borrow`]: ../../std/borrow/trait.Borrow.html /// -/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which -/// returns an [`Option`] or a [`Result`]. +/// **Note: this trait must not fail**. If the conversion can fail, use a +/// dedicated method which returns an [`Option`] or a [`Result`]. /// /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html @@ -77,12 +82,13 @@ use str::FromStr; /// # Generic Implementations /// /// - `AsRef` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// An example implementation of the trait is [`Path`]. /// -/// [`Path`]: ../../std/struct.Path.html +/// [`Path`]: ../../std/path/struct.Path.html /// /// ``` /// impl AsRef for str { @@ -119,8 +125,8 @@ pub trait AsRef { /// /// This trait is similar to `AsRef` but used for converting mutable references. /// -/// **Note: this trait must not fail**. If the conversion can fail, use a dedicated method which -/// returns an [`Option`] or a [`Result`]. +/// **Note: this trait must not fail**. If the conversion can fail, use a +/// dedicated method which returns an [`Option`] or a [`Result`]. /// /// [`Option`]: ../../std/option/enum.Option.html /// [`Result`]: ../../std/result/enum.Result.html @@ -128,7 +134,8 @@ pub trait AsRef { /// # Generic Implementations /// /// - `AsMut` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// @@ -161,14 +168,17 @@ pub trait AsMut { fn as_mut(&mut self) -> &mut T; } -/// A conversion that consumes `self`, which may or may not be expensive. The reciprocal of [`From`][From]. +/// A conversion that consumes `self`, which may or may not be expensive. The +/// reciprocal of [`From`][From]. /// -/// **Note: this trait must not fail**. If the conversion can fail, use [`TryInto`] or a dedicated -/// method which returns an [`Option`] or a [`Result`]. +/// **Note: this trait must not fail**. If the conversion can fail, use +/// [`TryInto`] or a dedicated method which returns an [`Option`] or a +/// [`Result`]. /// -/// Library authors should not directly implement this trait, but should prefer implementing -/// the [`From`][From] trait, which offers greater flexibility and provides an equivalent `Into` -/// implementation for free, thanks to a blanket implementation in the standard library. +/// Library authors should not directly implement this trait, but should prefer +/// implementing the [`From`][From] trait, which offers greater flexibility and +/// provides an equivalent `Into` implementation for free, thanks to a blanket +/// implementation in the standard library. /// /// # Generic Implementations /// @@ -202,18 +212,24 @@ pub trait Into: Sized { fn into(self) -> T; } -/// Simple and safe type conversions in to `Self`. It is the reciprocal of `Into`. +/// Simple and safe type conversions in to `Self`. It is the reciprocal of +/// `Into`. /// -/// This trait is useful when performing error handling as described by [the book][book] and is closely related to the `?` operator. +/// This trait is useful when performing error handling as described by +/// [the book][book] and is closely related to the `?` operator. /// -/// When constructing a function that is capable of failing the return type will generally be of the form `Result`. -/// The `From` trait allows for simplification of error handling by providing a means of returning a single error type that encapsulates -/// numerous possible erroneous situations. -/// This trait is not limited to error handling, rather the general case for this trait would be in any type conversions to have an -/// explicit definition of how they are performed. +/// When constructing a function that is capable of failing the return type +/// will generally be of the form `Result`. +/// The `From` trait allows for simplification of error handling by providing a +/// means of returning a single error type that encapsulates numerous possible +/// erroneous situations. +/// This trait is not limited to error handling, rather the general case for +/// this trait would be in any type conversions to have an explicit definition +/// of how they are performed. /// -/// **Note: this trait must not fail**. If the conversion can fail, use [`TryFrom`] or a dedicated -/// method which returns an [`Option`] or a [`Result`]. +/// **Note: this trait must not fail**. If the conversion can fail, use +/// [`TryFrom`] or a dedicated method which returns an [`Option`] or a +/// [`Result`]. /// /// # Generic Implementations /// @@ -265,7 +281,7 @@ pub trait Into: Sized { /// [`String`]: ../../std/string/struct.String.html /// [`Into`]: trait.Into.html /// [`from`]: trait.From.html#tymethod.from -/// [book]: ../../book/error-handling.html#the-from-trait +/// [book]: ../../book/error-handling.html #[stable(feature = "rust1", since = "1.0.0")] pub trait From: Sized { /// Performs the conversion. @@ -273,11 +289,13 @@ pub trait From: Sized { fn from(T) -> Self; } -/// An attempted conversion that consumes `self`, which may or may not be expensive. +/// An attempted conversion that consumes `self`, which may or may not be +/// expensive. /// -/// Library authors should not directly implement this trait, but should prefer implementing -/// the [`TryFrom`] trait, which offers greater flexibility and provides an equivalent `TryInto` -/// implementation for free, thanks to a blanket implementation in the standard library. +/// Library authors should not directly implement this trait, but should prefer +/// implementing the [`TryFrom`] trait, which offers greater flexibility and +/// provides an equivalent `TryInto` implementation for free, thanks to a +/// blanket implementation in the standard library. /// /// [`TryFrom`]: trait.TryFrom.html #[unstable(feature = "try_from", issue = "33417")] From bb8474682366592fa9d52cb11723a5fd5cd9421e Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Tue, 4 Apr 2017 08:27:20 +1000 Subject: [PATCH 5/8] AsMut example --- src/libcore/convert.rs | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 19cd2d3398f39..0bc0550641363 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -91,6 +91,8 @@ use str::FromStr; /// [`Path`]: ../../std/path/struct.Path.html /// /// ``` +/// use std::path::Path; +/// /// impl AsRef for str { /// fn as_ref(&self) -> &Path { /// Path::new(self) @@ -123,7 +125,8 @@ pub trait AsRef { /// A cheap, mutable reference-to-mutable reference conversion. /// -/// This trait is similar to `AsRef` but used for converting mutable references. +/// This trait is similar to `AsRef` but used for converting between mutable +/// references. /// /// **Note: this trait must not fail**. If the conversion can fail, use a /// dedicated method which returns an [`Option`] or a [`Result`]. @@ -153,11 +156,13 @@ pub trait AsRef { /// assert_eq!(*boxed_num, 1); /// ``` /// -/// Implementing `AsMut`: +/// `Vec` implements `AsMut` for converting between itself and a primitive array: /// /// ``` -/// impl Type { -/// let a = 1; +/// impl AsMut<[T]> for Vec { +/// fn as_mut(&mut self) -> &mut [T] { +/// self +/// } /// } /// ``` /// @@ -250,19 +255,22 @@ pub trait Into: Sized { /// An example usage for error handling: /// /// ``` +/// use std::io::{self, Read}; +/// use std::num; +/// /// enum CliError { /// IoError(io::Error), /// ParseError(num::ParseIntError), /// } /// -/// impl From for MyError { +/// impl From for CliError { /// fn from(error: io::Error) -> Self { /// CliError::IoError(error) /// } /// } /// -/// impl From for MyError { -/// fn from(error: io::Error) -> Self { +/// impl From for CliError { +/// fn from(error: num::ParseIntError) -> Self { /// CliError::ParseError(error) /// } /// } From d35fa1e98b244773129f18b0e8bcc81fa099ae68 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Fri, 7 Apr 2017 18:26:36 +1000 Subject: [PATCH 6/8] Removing broken examples --- src/libcore/convert.rs | 27 +++------------------------ 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index 0bc0550641363..abab4bb0f63b4 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -86,19 +86,6 @@ use str::FromStr; /// `&mut Foo` or `&&mut Foo`) /// /// # Examples -/// An example implementation of the trait is [`Path`]. -/// -/// [`Path`]: ../../std/path/struct.Path.html -/// -/// ``` -/// use std::path::Path; -/// -/// impl AsRef for str { -/// fn as_ref(&self) -> &Path { -/// Path::new(self) -/// } -/// } -/// ``` /// /// Both [`String`] and `&str` implement `AsRef`: /// @@ -156,15 +143,6 @@ pub trait AsRef { /// assert_eq!(*boxed_num, 1); /// ``` /// -/// `Vec` implements `AsMut` for converting between itself and a primitive array: -/// -/// ``` -/// impl AsMut<[T]> for Vec { -/// fn as_mut(&mut self) -> &mut [T] { -/// self -/// } -/// } -/// ``` /// #[stable(feature = "rust1", since = "1.0.0")] pub trait AsMut { @@ -275,11 +253,12 @@ pub trait Into: Sized { /// } /// } /// -/// fn open_and_parse_file(file_name: &str) -> Result { -/// let file = std::fs::File::open("test")?; +/// fn open_and_parse_file(file_name: &str) -> Result { +/// let mut file = std::fs::File::open("test")?; /// let mut contents = String::new(); /// file.read_to_string(&mut contents)?; /// let num: i32 = contents.trim().parse()?; +/// Ok(num) /// } /// ``` /// From 2877a01febe7a0667051463ed1bb431fe17c4d18 Mon Sep 17 00:00:00 2001 From: Dylan Maccora Date: Tue, 18 Apr 2017 08:29:05 +1000 Subject: [PATCH 7/8] Address review comments --- src/libcore/convert.rs | 43 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs index abab4bb0f63b4..084736685e3a7 100644 --- a/src/libcore/convert.rs +++ b/src/libcore/convert.rs @@ -35,7 +35,7 @@ //! - [`From`]` for T` implies [`Into`]` for U` //! - [`TryFrom`]` for T` implies [`TryInto`]` for U` //! - [`From`] and [`Into`] are reflexive, which means that all types can -//! `into()` themselves and `from()` themselves +//! `into` themselves and `from` themselves //! //! See each trait for usage examples. //! @@ -59,14 +59,15 @@ use str::FromStr; /// `AsRef` is to be used when wishing to convert to a reference of another /// type. /// `Borrow` is more related to the notion of taking the reference. It is -/// useful when wishing to abstract -/// over the type of reference (`&T`, `&mut T`) or allow both the referenced -/// and owned type to be treated in the same manner. +/// useful when wishing to abstract over the type of reference +/// (`&T`, `&mut T`) or allow both the referenced and owned type to be treated +/// in the same manner. +/// /// The key difference between the two traits is the intention: /// /// - Use `AsRef` when goal is to simply convert into a reference /// - Use `Borrow` when goal is related to writing code that is agnostic to the -/// type of borrow and if is reference or value +/// type of borrow and if is reference or value /// /// See [the book][book] for a more detailed comparison. /// @@ -82,8 +83,8 @@ use str::FromStr; /// # Generic Implementations /// /// - `AsRef` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type -/// `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// @@ -124,8 +125,8 @@ pub trait AsRef { /// # Generic Implementations /// /// - `AsMut` auto-dereferences if the inner type is a reference or a mutable -/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type -/// `&mut Foo` or `&&mut Foo`) +/// reference (e.g.: `foo.as_ref()` will work the same if `foo` has type +/// `&mut Foo` or `&&mut Foo`) /// /// # Examples /// @@ -203,9 +204,11 @@ pub trait Into: Sized { /// /// When constructing a function that is capable of failing the return type /// will generally be of the form `Result`. +/// /// The `From` trait allows for simplification of error handling by providing a /// means of returning a single error type that encapsulates numerous possible /// erroneous situations. +/// /// This trait is not limited to error handling, rather the general case for /// this trait would be in any type conversions to have an explicit definition /// of how they are performed. @@ -310,8 +313,7 @@ pub trait TryFrom: Sized { // As lifts over & #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T - where T: AsRef +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T where T: AsRef { fn as_ref(&self) -> &U { >::as_ref(*self) @@ -320,8 +322,7 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a T // As lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T - where T: AsRef +impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T where T: AsRef { fn as_ref(&self) -> &U { >::as_ref(*self) @@ -338,8 +339,7 @@ impl<'a, T: ?Sized, U: ?Sized> AsRef for &'a mut T // AsMut lifts over &mut #[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T - where T: AsMut +impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T where T: AsMut { fn as_mut(&mut self) -> &mut U { (*self).as_mut() @@ -356,8 +356,7 @@ impl<'a, T: ?Sized, U: ?Sized> AsMut for &'a mut T // From implies Into #[stable(feature = "rust1", since = "1.0.0")] -impl Into for T - where U: From +impl Into for T where U: From { fn into(self) -> U { U::from(self) @@ -367,16 +366,13 @@ impl Into for T // From (and thus Into) is reflexive #[stable(feature = "rust1", since = "1.0.0")] impl From for T { - fn from(t: T) -> T { - t - } + fn from(t: T) -> T { t } } // TryFrom implies TryInto #[unstable(feature = "try_from", issue = "33417")] -impl TryInto for T - where U: TryFrom +impl TryInto for T where U: TryFrom { type Error = U::Error; @@ -413,8 +409,7 @@ impl AsRef for str { // FromStr implies TryFrom<&str> #[unstable(feature = "try_from", issue = "33417")] -impl<'a, T> TryFrom<&'a str> for T - where T: FromStr +impl<'a, T> TryFrom<&'a str> for T where T: FromStr { type Error = ::Err; From df383b95476d59c26e822bcda69d3255da61622c Mon Sep 17 00:00:00 2001 From: Michael Gattozzi Date: Wed, 19 Apr 2017 14:00:50 -0400 Subject: [PATCH 8/8] Fix link for wait --- src/libstd/process.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/process.rs b/src/libstd/process.rs index edcf206501a08..9d7f87f06c31c 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -78,7 +78,7 @@ use sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; /// run, even after the `Child` handle to the child process has gone out of /// scope. /// -/// Calling [`wait`] (or other functions that wrap around it) will make +/// Calling [`wait`](#method.wait) (or other functions that wrap around it) will make /// the parent process wait until the child has actually exited before /// continuing. ///