Auto merge of #24328 - Manishearth:rollup, r=Manishearth

2 files changed, 68 insertions, 26 deletions

diff --git a/src/libcore/convert.rs b/src/libcore/convert.rs
index 85b648bbd59..1c1ad5fd33f 100644
--- a/src/libcore/convert.rs
+++ b/src/libcore/convert.rs
@@ -10,15 +10,35 @@
 
 //! Traits for conversions between types.
 //!
-//! The traits in this module provide a general way to talk about
-//! conversions from one type to another. They follow the standard
-//! Rust conventions of `as`/`to`/`into`/`from`.
+//! The traits in this module provide a general way to talk about conversions from one type to
+//! another. They follow the standard Rust conventions of `as`/`to`/`into`/`from`.
+//!
+//! Like many traits, these are often used as bounds for generic functions, to support arguments of
+//! multiple types.
+//!
+//! See each trait for usage examples.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
 use marker::Sized;
 
 /// A cheap, reference-to-reference conversion.
+///
+/// # Examples
+///
+/// Both `String` and `&str` implement `AsRef<str>`:
+///
+/// ```
+/// fn is_hello<T: AsRef<str>>(s: T) {
+///    assert_eq!("hello", s.as_ref());
+/// }
+///
+/// let s = "hello";
+/// is_hello(s);
+///
+/// let s = "hello".to_string();
+/// is_hello(s);
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait AsRef<T: ?Sized> {
     /// Performs the conversion.
@@ -34,8 +54,21 @@ pub trait AsMut<T: ?Sized> {
     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.
+///
+/// # Examples
+///
+/// `String` implements `Into<Vec<u8>>`:
+///
+/// ```
+/// fn is_hello<T: Into<Vec<u8>>>(s: T) {
+///    let bytes = b"hello".to_vec();
+///    assert_eq!(bytes, s.into());
+/// }
+///
+/// let s = "hello".to_string();
+/// is_hello(s);
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Into<T>: Sized {
     /// Performs the conversion.
@@ -44,6 +77,19 @@ pub trait Into<T>: Sized {
 }
 
 /// Construct `Self` via a conversion.
+///
+/// # Examples
+///
+/// `String` implements `From<&str>`:
+///
+/// ```
+/// let s = "hello";
+/// let string = "hello".to_string();
+///
+/// let other_string: String = From::from(s);
+///
+/// assert_eq!(string, other_string);
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait From<T> {
     /// Performs the conversion.
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 9007a5142c3..4e4a928d91f 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -217,7 +217,7 @@ pub trait Int
                reason = "pending integer conventions")]
     fn trailing_zeros(self) -> u32;
 
-    /// Shifts the bits to the left by a specified amount amount, `n`, wrapping
+    /// Shifts the bits to the left by a specified amount, `n`, wrapping
     /// the truncated bits to the end of the resulting integer.
     ///
     /// # Examples
@@ -235,7 +235,7 @@ pub trait Int
                reason = "pending integer conventions")]
     fn rotate_left(self, n: u32) -> Self;
 
-    /// Shifts the bits to the right by a specified amount amount, `n`, wrapping
+    /// Shifts the bits to the right by a specified amount, `n`, wrapping
     /// the truncated bits to the beginning of the resulting integer.
     ///
     /// # Examples
@@ -856,9 +856,8 @@ macro_rules! int_impl {
         ///
         /// # Return value
         ///
-        /// `None` if the string did not represent a valid number.
-        /// Otherwise, `Some(n)` where `n` is the integer represented
-        /// by `src`.
+        /// `Err(ParseIntError)` if the string did not represent a valid number.
+        /// Otherwise, `Ok(n)` where `n` is the integer represented by `src`.
         #[stable(feature = "rust1", since = "1.0.0")]
         #[allow(deprecated)]
         pub fn from_str_radix(src: &str, radix: u32) -> Result<$T, ParseIntError> {
@@ -937,7 +936,7 @@ macro_rules! int_impl {
             (self as $UnsignedT).trailing_zeros()
         }
 
-        /// Shifts the bits to the left by a specified amount amount, `n`,
+        /// Shifts the bits to the left by a specified amount, `n`,
         /// wrapping the truncated bits to the end of the resulting integer.
         ///
         /// # Examples
@@ -957,7 +956,7 @@ macro_rules! int_impl {
             (self as $UnsignedT).rotate_left(n) as $T
         }
 
-        /// Shifts the bits to the right by a specified amount amount, `n`,
+        /// Shifts the bits to the right by a specified amount, `n`,
         /// wrapping the truncated bits to the beginning of the resulting
         /// integer.
         ///
@@ -1224,11 +1223,10 @@ macro_rules! int_impl {
         ///
         /// # Examples
         ///
-        /// ```rust
-        /// # #![feature(core)]
-        /// use std::num::Int;
+        /// ```
+        /// let x: i32 = 2; // or any other integer type
         ///
-        /// assert_eq!(2.pow(4), 16);
+        /// assert_eq!(x.pow(4), 16);
         /// ```
         #[stable(feature = "rust1", since = "1.0.0")]
         #[inline]
@@ -1374,9 +1372,8 @@ macro_rules! uint_impl {
         ///
         /// # Return value
         ///
-        /// `None` if the string did not represent a valid number.
-        /// Otherwise, `Some(n)` where `n` is the integer represented
-        /// by `src`.
+        /// `Err(ParseIntError)` if the string did not represent a valid number.
+        /// Otherwise, `Ok(n)` where `n` is the integer represented by `src`.
         #[stable(feature = "rust1", since = "1.0.0")]
         #[allow(deprecated)]
         pub fn from_str_radix(src: &str, radix: u32) -> Result<$T, ParseIntError> {
@@ -1457,7 +1454,7 @@ macro_rules! uint_impl {
             unsafe { $cttz(self as $ActualT) as u32 }
         }
 
-        /// Shifts the bits to the left by a specified amount amount, `n`,
+        /// Shifts the bits to the left by a specified amount, `n`,
         /// wrapping the truncated bits to the end of the resulting integer.
         ///
         /// # Examples
@@ -1479,7 +1476,7 @@ macro_rules! uint_impl {
             (self << n) | (self >> (($BITS - n) % $BITS))
         }
 
-        /// Shifts the bits to the right by a specified amount amount, `n`,
+        /// Shifts the bits to the right by a specified amount, `n`,
         /// wrapping the truncated bits to the beginning of the resulting
         /// integer.
         ///
@@ -2708,8 +2705,8 @@ macro_rules! from_str_radix_float_impl {
             ///
             /// # Return value
             ///
-            /// `None` if the string did not represent a valid number.  Otherwise,
-            /// `Some(n)` where `n` is the floating-point number represented by `src`.
+            /// `Err(ParseIntError)` if the string did not represent a valid number.  Otherwise,
+            /// Otherwise, `Ok(n)` where `n` is the floating-point number represented by `src`.
             #[inline]
             #[allow(deprecated)]
             fn from_str(src: &str) -> Result<$T, ParseFloatError> {
@@ -2737,9 +2734,8 @@ macro_rules! from_str_radix_float_impl {
             ///
             /// # Return value
             ///
-            /// `None` if the string did not represent a valid number.
-            /// Otherwise, `Some(n)` where `n` is the floating-point number
-            /// represented by `src`.
+            /// `Err(ParseIntError)` if the string did not represent a valid number.  Otherwise,
+            /// Otherwise, `Ok(n)` where `n` is the floating-point number represented by `src`.
             fn from_str_radix(src: &str, radix: u32)
                               -> Result<$T, ParseFloatError> {
                 use self::FloatErrorKind::*;