Auto merge of #24433 - alexcrichton:rollup, r=alexcrichton

16 files changed, 255 insertions, 320 deletions

diff --git a/src/libcore/any.rs b/src/libcore/any.rs
index 7025c76d92c..85b8accadf3 100644
--- a/src/libcore/any.rs
+++ b/src/libcore/any.rs
@@ -91,7 +91,7 @@ use marker::{Reflect, Sized};
 /// [mod]: index.html
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Any: Reflect + 'static {
-    /// Get the `TypeId` of `self`
+    /// Gets the `TypeId` of `self`.
     #[unstable(feature = "core",
                reason = "this method will likely be replaced by an associated static")]
     fn get_type_id(&self) -> TypeId;
diff --git a/src/libcore/atomic.rs b/src/libcore/atomic.rs
index ed35e095492..02f9ee506f9 100644
--- a/src/libcore/atomic.rs
+++ b/src/libcore/atomic.rs
@@ -78,12 +78,20 @@ use intrinsics;
 use cell::UnsafeCell;
 use marker::PhantomData;
 
+use default::Default;
+
 /// A boolean type which can be safely shared between threads.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct AtomicBool {
     v: UnsafeCell<usize>,
 }
 
+impl Default for AtomicBool {
+    fn default() -> AtomicBool {
+        ATOMIC_BOOL_INIT
+    }
+}
+
 unsafe impl Sync for AtomicBool {}
 
 /// A signed integer type which can be safely shared between threads.
@@ -92,6 +100,12 @@ pub struct AtomicIsize {
     v: UnsafeCell<isize>,
 }
 
+impl Default for AtomicIsize {
+    fn default() -> AtomicIsize {
+        ATOMIC_ISIZE_INIT
+    }
+}
+
 unsafe impl Sync for AtomicIsize {}
 
 /// An unsigned integer type which can be safely shared between threads.
@@ -100,6 +114,12 @@ pub struct AtomicUsize {
     v: UnsafeCell<usize>,
 }
 
+impl Default for AtomicUsize {
+    fn default() -> AtomicUsize {
+        ATOMIC_USIZE_INIT
+    }
+}
+
 unsafe impl Sync for AtomicUsize {}
 
 /// A raw pointer type which can be safely shared between threads.
diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index 76e09eedbdf..df0de234b9a 100644
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -211,7 +211,7 @@ impl<T:Copy> Cell<T> {
         }
     }
 
-    /// Get a reference to the underlying `UnsafeCell`.
+    /// Gets a reference to the underlying `UnsafeCell`.
     ///
     /// # Unsafety
     ///
@@ -436,7 +436,7 @@ impl<T> RefCell<T> {
         }
     }
 
-    /// Get a reference to the underlying `UnsafeCell`.
+    /// Gets a reference to the underlying `UnsafeCell`.
     ///
     /// This can be used to circumvent `RefCell`'s safety checks.
     ///
@@ -537,7 +537,7 @@ impl<'b, T> Deref for Ref<'b, T> {
     }
 }
 
-/// Copy a `Ref`.
+/// Copies a `Ref`.
 ///
 /// The `RefCell` is already immutably borrowed, so this cannot fail.
 ///
@@ -647,7 +647,7 @@ pub struct UnsafeCell<T> {
 impl<T> !Sync for UnsafeCell<T> {}
 
 impl<T> UnsafeCell<T> {
-    /// Construct a new instance of `UnsafeCell` which will wrap the specified
+    /// Constructs a new instance of `UnsafeCell` which will wrap the specified
     /// value.
     ///
     /// All access to the inner value through methods is `unsafe`, and it is highly discouraged to
@@ -685,7 +685,7 @@ impl<T> UnsafeCell<T> {
         &self.value as *const T as *mut T
     }
 
-    /// Unwraps the value
+    /// Unwraps the value.
     ///
     /// # Unsafety
     ///
diff --git a/src/libcore/clone.rs b/src/libcore/clone.rs
index 311901b43d4..f11c01507dc 100644
--- a/src/libcore/clone.rs
+++ b/src/libcore/clone.rs
@@ -38,7 +38,7 @@ pub trait Clone : Sized {
     #[stable(feature = "rust1", since = "1.0.0")]
     fn clone(&self) -> Self;
 
-    /// Perform copy-assignment from `source`.
+    /// Performs copy-assignment from `source`.
     ///
     /// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality,
     /// but can be overridden to reuse the resources of `a` to avoid unnecessary
@@ -52,7 +52,7 @@ pub trait Clone : Sized {
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<'a, T: ?Sized> Clone for &'a T {
-    /// Return a shallow copy of the reference.
+    /// Returns a shallow copy of the reference.
     #[inline]
     fn clone(&self) -> &'a T { *self }
 }
@@ -61,7 +61,7 @@ macro_rules! clone_impl {
     ($t:ty) => {
         #[stable(feature = "rust1", since = "1.0.0")]
         impl Clone for $t {
-            /// Return a deep copy of the value.
+            /// Returns a deep copy of the value.
             #[inline]
             fn clone(&self) -> $t { *self }
         }
@@ -92,28 +92,28 @@ macro_rules! extern_fn_clone {
         #[unstable(feature = "core",
                    reason = "this may not be sufficient for fns with region parameters")]
         impl<$($A,)* ReturnType> Clone for extern "Rust" fn($($A),*) -> ReturnType {
-            /// Return a copy of a function pointer
+            /// Returns a copy of a function pointer.
             #[inline]
             fn clone(&self) -> extern "Rust" fn($($A),*) -> ReturnType { *self }
         }
 
         #[unstable(feature = "core", reason = "brand new")]
         impl<$($A,)* ReturnType> Clone for extern "C" fn($($A),*) -> ReturnType {
-            /// Return a copy of a function pointer
+            /// Returns a copy of a function pointer.
             #[inline]
             fn clone(&self) -> extern "C" fn($($A),*) -> ReturnType { *self }
         }
 
         #[unstable(feature = "core", reason = "brand new")]
         impl<$($A,)* ReturnType> Clone for unsafe extern "Rust" fn($($A),*) -> ReturnType {
-            /// Return a copy of a function pointer
+            /// Returns a copy of a function pointer.
             #[inline]
             fn clone(&self) -> unsafe extern "Rust" fn($($A),*) -> ReturnType { *self }
         }
 
         #[unstable(feature = "core", reason = "brand new")]
         impl<$($A,)* ReturnType> Clone for unsafe extern "C" fn($($A),*) -> ReturnType {
-            /// Return a copy of a function pointer
+            /// Returns a copy of a function pointer.
             #[inline]
             fn clone(&self) -> unsafe extern "C" fn($($A),*) -> ReturnType { *self }
         }
diff --git a/src/libcore/fmt/float.rs b/src/libcore/fmt/float.rs
index 5f19bc5be98..72c25c68040 100644
--- a/src/libcore/fmt/float.rs
+++ b/src/libcore/fmt/float.rs
@@ -1,4 +1,4 @@
-// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2013-2015 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -8,14 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#![allow(missing_docs)]
-
 pub use self::ExponentFormat::*;
 pub use self::SignificantDigits::*;
-pub use self::SignFormat::*;
 
-use char;
-use char::CharExt;
+use char::{self, CharExt};
 use fmt;
 use iter::Iterator;
 use num::{cast, Float, ToPrimitive};
@@ -46,50 +42,29 @@ pub enum SignificantDigits {
     DigExact(usize)
 }
 
-/// How to emit the sign of a number.
-pub enum SignFormat {
-    /// `-` will be printed for negative values, but no sign will be emitted
-    /// for positive numbers.
-    SignNeg
-}
-
-const DIGIT_E_RADIX: u32 = ('e' as u32) - ('a' as u32) + 11;
-
-/// Converts a number to its string representation as a byte vector.
-/// This is meant to be a common base implementation for all numeric string
-/// conversion functions like `to_string()` or `to_str_radix()`.
+/// Converts a float number to its string representation.
+/// This is meant to be a common base implementation for various formatting styles.
+/// The number is assumed to be non-negative, callers use `Formatter::pad_integral`
+/// to add the right sign, if any.
 ///
 /// # Arguments
 ///
-/// - `num`           - The number to convert. Accepts any number that
+/// - `num`           - The number to convert (non-negative). Accepts any number that
 ///                     implements the numeric traits.
-/// - `radix`         - Base to use. Accepts only the values 2-36. If the exponential notation
-///                     is used, then this base is only used for the significand. The exponent
-///                     itself always printed using a base of 10.
-/// - `negative_zero` - Whether to treat the special value `-0` as
-///                     `-0` or as `+0`.
-/// - `sign`          - How to emit the sign. See `SignFormat`.
 /// - `digits`        - The amount of digits to use for emitting the fractional
 ///                     part, if any. See `SignificantDigits`.
 /// - `exp_format`   - Whether or not to use the exponential (scientific) notation.
 ///                    See `ExponentFormat`.
 /// - `exp_capital`   - Whether or not to use a capital letter for the exponent sign, if
 ///                     exponential notation is desired.
-/// - `f`             - A closure to invoke with the bytes representing the
+/// - `f`             - A closure to invoke with the string representing the
 ///                     float.
 ///
 /// # Panics
 ///
-/// - Panics if `radix` < 2 or `radix` > 36.
-/// - Panics if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
-///   between digit and exponent sign `'e'`.
-/// - Panics if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
-///   between digit and exponent sign `'p'`.
+/// - Panics if `num` is negative.
 pub fn float_to_str_bytes_common<T: Float, U, F>(
     num: T,
-    radix: u32,
-    negative_zero: bool,
-    sign: SignFormat,
     digits: SignificantDigits,
     exp_format: ExponentFormat,
     exp_upper: bool,
@@ -97,16 +72,12 @@ pub fn float_to_str_bytes_common<T: Float, U, F>(
 ) -> U where
     F: FnOnce(&str) -> U,
 {
-    assert!(2 <= radix && radix <= 36);
-    match exp_format {
-        ExpDec if radix >= DIGIT_E_RADIX       // decimal exponent 'e'
-          => panic!("float_to_str_bytes_common: radix {} incompatible with \
-                    use of 'e' as decimal exponent", radix),
-        _ => ()
-    }
-
     let _0: T = Float::zero();
     let _1: T = Float::one();
+    let radix: u32 = 10;
+    let radix_f: T = cast(radix).unwrap();
+
+    assert!(num.is_nan() || num >= _0, "float_to_str_bytes_common: number is negative");
 
     match num.classify() {
         Fp::Nan => return f("NaN"),
@@ -119,41 +90,28 @@ pub fn float_to_str_bytes_common<T: Float, U, F>(
         _ => {}
     }
 
-    let neg = num < _0 || (negative_zero && _1 / num == Float::neg_infinity());
-    // For an f64 the exponent is in the range of [-1022, 1023] for base 2, so
-    // we may have up to that many digits. Give ourselves some extra wiggle room
-    // otherwise as well.
-    let mut buf = [0; 1536];
+    // For an f64 the (decimal) exponent is roughly in the range of [-307, 308], so
+    // we may have up to that many digits. We err on the side of caution and
+    // add 50% extra wiggle room.
+    let mut buf = [0; 462];
     let mut end = 0;
-    let radix_gen: T = cast(radix as isize).unwrap();
 
     let (num, exp) = match exp_format {
-        ExpNone => (num, 0),
-        ExpDec if num == _0 => (num, 0),
-        ExpDec => {
-            let (exp, exp_base) = match exp_format {
-                ExpDec => (num.abs().log10().floor(), cast::<f64, T>(10.0f64).unwrap()),
-                ExpNone => panic!("unreachable"),
-            };
-
-            (num / exp_base.powf(exp), cast::<T, i32>(exp).unwrap())
+        ExpDec if num != _0 => {
+            let exp = num.log10().floor();
+            (num / radix_f.powf(exp), cast::<T, i32>(exp).unwrap())
         }
+        _ => (num, 0)
     };
 
     // First emit the non-fractional part, looping at least once to make
     // sure at least a `0` gets emitted.
     let mut deccum = num.trunc();
     loop {
-        // Calculate the absolute value of each digit instead of only
-        // doing it once for the whole number because a
-        // representable negative number doesn't necessary have an
-        // representable additive inverse of the same type
-        // (See twos complement). But we assume that for the
-        // numbers [-35 .. 0] we always have [0 .. 35].
-        let current_digit = (deccum % radix_gen).abs();
+        let current_digit = deccum % radix_f;
 
         // Decrease the deccumulator one digit at a time
-        deccum = deccum / radix_gen;
+        deccum = deccum / radix_f;
         deccum = deccum.trunc();
 
         let c = char::from_digit(current_digit.to_isize().unwrap() as u32, radix);
@@ -170,15 +128,6 @@ pub fn float_to_str_bytes_common<T: Float, U, F>(
         DigExact(count) => (true, count + 1, true)
     };
 
-    // Decide what sign to put in front
-    match sign {
-        SignNeg if neg => {
-            buf[end] = b'-';
-            end += 1;
-        }
-        _ => ()
-    }
-
     buf[..end].reverse();
 
     // Remember start of the fractional digits.
@@ -205,14 +154,11 @@ pub fn float_to_str_bytes_common<T: Float, U, F>(
               )
         ) {
             // Shift first fractional digit into the integer part
-            deccum = deccum * radix_gen;
+            deccum = deccum * radix_f;
 
-            // Calculate the absolute value of each digit.
-            // See note in first loop.
-            let current_digit = deccum.trunc().abs();
+            let current_digit = deccum.trunc();
 
-            let c = char::from_digit(current_digit.to_isize().unwrap() as u32,
-                                     radix);
+            let c = char::from_digit(current_digit.to_isize().unwrap() as u32, radix);
             buf[end] = c.unwrap() as u8;
             end += 1;
 
@@ -301,12 +247,8 @@ pub fn float_to_str_bytes_common<T: Float, U, F>(
 
     match exp_format {
         ExpNone => {},
-        _ => {
-            buf[end] = match exp_format {
-                ExpDec if exp_upper => 'E',
-                ExpDec if !exp_upper => 'e',
-                _ => panic!("unreachable"),
-            } as u8;
+        ExpDec => {
+            buf[end] = if exp_upper { b'E' } else { b'e' };
             end += 1;
 
             struct Filler<'a> {
@@ -324,11 +266,7 @@ pub fn float_to_str_bytes_common<T: Float, U, F>(
             }
 
             let mut filler = Filler { buf: &mut buf, end: &mut end };
-            match sign {
-                SignNeg => {
-                    let _ = fmt::write(&mut filler, format_args!("{:-}", exp));
-                }
-            }
+            let _ = fmt::write(&mut filler, format_args!("{:-}", exp));
         }
     }
 
diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs
index 1c70f9941f7..80c661b260c 100644
--- a/src/libcore/fmt/mod.rs
+++ b/src/libcore/fmt/mod.rs
@@ -1,4 +1,4 @@
-// Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2013-2015 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -18,6 +18,7 @@ use clone::Clone;
 use iter::Iterator;
 use marker::{Copy, PhantomData, Sized};
 use mem;
+use num::Float;
 use option::Option;
 use option::Option::{Some, None};
 use result::Result::Ok;
@@ -910,33 +911,38 @@ impl<'a, T> Pointer for &'a mut T {
     }
 }
 
+// Common code of floating point Debug and Display.
+fn float_to_str_common<T: Float, F>(num: &T, precision: Option<usize>, post: F) -> Result
+        where F : FnOnce(&str) -> Result {
+    let digits = match precision {
+        Some(i) => float::DigExact(i),
+        None => float::DigMax(6),
+    };
+    float::float_to_str_bytes_common(num.abs(),
+                                     digits,
+                                     float::ExpNone,
+                                     false,
+                                     post)
+}
+
 macro_rules! floating { ($ty:ident) => {
 
     #[stable(feature = "rust1", since = "1.0.0")]
     impl Debug for $ty {
         fn fmt(&self, fmt: &mut Formatter) -> Result {
-            Display::fmt(self, fmt)
+            float_to_str_common(self, fmt.precision, |absolute| {
+                // is_positive() counts -0.0 as negative
+                fmt.pad_integral(self.is_nan() || self.is_positive(), "", absolute)
+            })
         }
     }
 
     #[stable(feature = "rust1", since = "1.0.0")]
     impl Display for $ty {
         fn fmt(&self, fmt: &mut Formatter) -> Result {
-            use num::Float;
-
-            let digits = match fmt.precision {
-                Some(i) => float::DigExact(i),
-                None => float::DigMax(6),
-            };
-            float::float_to_str_bytes_common(self.abs(),
-                                             10,
-                                             true,
-                                             float::SignNeg,
-                                             digits,
-                                             float::ExpNone,
-                                             false,
-                                             |bytes| {
-                fmt.pad_integral(self.is_nan() || *self >= 0.0, "", bytes)
+            float_to_str_common(self, fmt.precision, |absolute| {
+                // simple comparison counts -0.0 as positive
+                fmt.pad_integral(self.is_nan() || *self >= 0.0, "", absolute)
             })
         }
     }
@@ -951,9 +957,6 @@ macro_rules! floating { ($ty:ident) => {
                 None => float::DigMax(6),
             };
             float::float_to_str_bytes_common(self.abs(),
-                                             10,
-                                             true,
-                                             float::SignNeg,
                                              digits,
                                              float::ExpDec,
                                              false,
@@ -973,9 +976,6 @@ macro_rules! floating { ($ty:ident) => {
                 None => float::DigMax(6),
             };
             float::float_to_str_bytes_common(self.abs(),
-                                             10,
-                                             true,
-                                             float::SignNeg,
                                              digits,
                                              float::ExpDec,
                                              true,
diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs
index 80f506ebc06..8ed89adec5b 100644
--- a/src/libcore/intrinsics.rs
+++ b/src/libcore/intrinsics.rs
@@ -139,16 +139,16 @@ extern "rust-intrinsic" {
     pub fn atomic_fence_rel();
     pub fn atomic_fence_acqrel();
 
-    /// Abort the execution of the process.
+    /// Aborts the execution of the process.
     pub fn abort() -> !;
 
-    /// Tell LLVM that this point in the code is not reachable,
+    /// Tells LLVM that this point in the code is not reachable,
     /// enabling further optimizations.
     ///
     /// NB: This is very different from the `unreachable!()` macro!
     pub fn unreachable() -> !;
 
-    /// Inform the optimizer that a condition is always true.
+    /// Informs the optimizer that a condition is always true.
     /// If the condition is false, the behavior is undefined.
     ///
     /// No code is generated for this intrinsic, but the optimizer will try
@@ -158,7 +158,7 @@ extern "rust-intrinsic" {
     /// own, or if it does not enable any significant optimizations.
     pub fn assume(b: bool);
 
-    /// Execute a breakpoint trap, for inspection by a debugger.
+    /// Executes a breakpoint trap, for inspection by a debugger.
     pub fn breakpoint();
 
     /// The size of a type in bytes.
@@ -170,7 +170,7 @@ extern "rust-intrinsic" {
     /// elements.
     pub fn size_of<T>() -> usize;
 
-    /// Move a value to an uninitialized memory location.
+    /// Moves a value to an uninitialized memory location.
     ///
     /// Drop glue is not run on the destination.
     pub fn move_val_init<T>(dst: &mut T, src: T);
@@ -186,7 +186,7 @@ extern "rust-intrinsic" {
     /// crate it is invoked in.
     pub fn type_id<T: ?Sized + 'static>() -> u64;
 
-    /// Create a value initialized to so that its drop flag,
+    /// Creates a value initialized to so that its drop flag,
     /// if any, says that it has been dropped.
     ///
     /// `init_dropped` is unsafe because it returns a datum with all
@@ -199,7 +199,7 @@ extern "rust-intrinsic" {
     /// intrinsic).
     pub fn init_dropped<T>() -> T;
 
-    /// Create a value initialized to zero.
+    /// Creates a value initialized to zero.
     ///
     /// `init` is unsafe because it returns a zeroed-out datum,
     /// which is unsafe unless T is `Copy`.  Also, even if T is
@@ -207,7 +207,7 @@ extern "rust-intrinsic" {
     /// state for the type in question.
     pub fn init<T>() -> T;
 
-    /// Create an uninitialized value.
+    /// Creates an uninitialized value.
     ///
     /// `uninit` is unsafe because there is no guarantee of what its
     /// contents are. In particular its drop-flag may be set to any
@@ -216,7 +216,7 @@ extern "rust-intrinsic" {
     /// initialize memory previous set to the result of `uninit`.
     pub fn uninit<T>() -> T;
 
-    /// Move a value out of scope without running drop glue.
+    /// Moves a value out of scope without running drop glue.
     ///
     /// `forget` is unsafe because the caller is responsible for
     /// ensuring the argument is deallocated already.
diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index c756d3cb9c2..4a0706906ee 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -91,7 +91,7 @@ pub trait Iterator {
     #[stable(feature = "rust1", since = "1.0.0")]
     type Item;
 
-    /// Advance the iterator and return the next value. Return `None` when the
+    /// Advances the iterator and returns the next value. Returns `None` when the
     /// end is reached.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn next(&mut self) -> Option<Self::Item>;
@@ -670,7 +670,7 @@ pub trait Iterator {
         None
     }
 
-    /// Return the index of the first element satisfying the specified predicate
+    /// Returns the index of the first element satisfying the specified predicate
     ///
     /// Does not consume the iterator past the first found element.
     ///
@@ -698,7 +698,7 @@ pub trait Iterator {
         None
     }
 
-    /// Return the index of the last element satisfying the specified predicate
+    /// Returns the index of the last element satisfying the specified predicate
     ///
     /// If no element matches, None is returned.
     ///
@@ -853,7 +853,7 @@ pub trait Iterator {
         MinMax(min, max)
     }
 
-    /// Return the element that gives the maximum value from the
+    /// Returns the element that gives the maximum value from the
     /// specified function.
     ///
     /// Returns the rightmost element if the comparison determines two elements
@@ -882,7 +882,7 @@ pub trait Iterator {
             .map(|(_, x)| x)
     }
 
-    /// Return the element that gives the minimum value from the
+    /// Returns the element that gives the minimum value from the
     /// specified function.
     ///
     /// Returns the leftmost element if the comparison determines two elements
@@ -1099,7 +1099,7 @@ impl<'a, I: Iterator + ?Sized> Iterator for &'a mut I {
 #[rustc_on_unimplemented="a collection of type `{Self}` cannot be \
                           built from an iterator over elements of type `{A}`"]
 pub trait FromIterator<A> {
-    /// Build a container with elements from something iterable.
+    /// Builds a container with elements from something iterable.
     ///
     /// # Examples
     ///
@@ -1158,7 +1158,7 @@ impl<I: Iterator> IntoIterator for I {
 /// A type growable from an `Iterator` implementation
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Extend<A> {
-    /// Extend a container with the elements yielded by an arbitrary iterator
+    /// Extends a container with the elements yielded by an arbitrary iterator
     #[stable(feature = "rust1", since = "1.0.0")]
     fn extend<T: IntoIterator<Item=A>>(&mut self, iterable: T);
 }
@@ -1170,7 +1170,7 @@ pub trait Extend<A> {
 /// independently of each other.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait DoubleEndedIterator: Iterator {
-    /// Yield an element from the end of the range, returning `None` if the
+    /// Yields an element from the end of the range, returning `None` if the
     /// range is empty.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn next_back(&mut self) -> Option<Self::Item>;
@@ -1191,11 +1191,11 @@ impl<'a, I: DoubleEndedIterator + ?Sized> DoubleEndedIterator for &'a mut I {
            reason = "not widely used, may be better decomposed into Index \
                      and ExactSizeIterator")]
 pub trait RandomAccessIterator: Iterator {
-    /// Return the number of indexable elements. At most `std::usize::MAX`
+    /// Returns the number of indexable elements. At most `std::usize::MAX`
     /// elements are indexable, even if the iterator represents a longer range.
     fn indexable(&self) -> usize;
 
-    /// Return an element at an index, or `None` if the index is out of bounds
+    /// Returns an element at an index, or `None` if the index is out of bounds
     fn idx(&mut self, index: usize) -> Option<Self::Item>;
 }
 
@@ -1210,7 +1210,7 @@ pub trait RandomAccessIterator: Iterator {
 pub trait ExactSizeIterator: Iterator {
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
-    /// Return the exact length of the iterator.
+    /// Returns the exact length of the iterator.
     fn len(&self) -> usize {
         let (lower, upper) = self.size_hint();
         // Note: This assertion is overly defensive, but it checks the invariant
@@ -1856,7 +1856,7 @@ impl<I: ExactSizeIterator> ExactSizeIterator for Peekable<I> {}
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<I: Iterator> Peekable<I> {
-    /// Return a reference to the next element of the iterator with out
+    /// Returns a reference to the next element of the iterator with out
     /// advancing it, or None if the iterator is exhausted.
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -1870,7 +1870,7 @@ impl<I: Iterator> Peekable<I> {
         }
     }
 
-    /// Check whether peekable iterator is empty or not.
+    /// Checks whether peekable iterator is empty or not.
     #[inline]
     pub fn is_empty(&mut self) -> bool {
         self.peek().is_none()
@@ -2401,12 +2401,12 @@ pub trait Step: PartialOrd {
     /// Steps `self` if possible.
     fn step(&self, by: &Self) -> Option<Self>;
 
-    /// The number of steps between two step objects.
+    /// Returns the number of steps between two step objects.
     ///
     /// `start` should always be less than `end`, so the result should never
     /// be negative.
     ///
-    /// Return `None` if it is not possible to calculate steps_between
+    /// Returns `None` if it is not possible to calculate steps_between
     /// without overflow.
     fn steps_between(start: &Self, end: &Self, by: &Self) -> Option<usize>;
 }
@@ -2549,7 +2549,7 @@ pub struct RangeInclusive<A> {
     done: bool,
 }
 
-/// Return an iterator over the range [start, stop]
+/// Returns an iterator over the range [start, stop].
 #[inline]
 #[unstable(feature = "core",
            reason = "likely to be replaced by range notation and adapters")]
@@ -2657,7 +2657,7 @@ pub struct RangeStepInclusive<A> {
     done: bool,
 }
 
-/// Return an iterator over the range [start, stop] by `step`.
+/// Returns an iterator over the range [start, stop] by `step`.
 ///
 /// It handles overflow by stopping.
 ///
@@ -2827,7 +2827,7 @@ type IterateState<T, F> = (F, Option<T>, bool);
 #[unstable(feature = "core")]
 pub type Iterate<T, F> = Unfold<IterateState<T, F>, fn(&mut IterateState<T, F>) -> Option<T>>;
 
-/// Create a new iterator that produces an infinite sequence of
+/// Creates a new iterator that produces an infinite sequence of
 /// repeated applications of the given function `f`.
 #[unstable(feature = "core")]
 pub fn iterate<T, F>(seed: T, f: F) -> Iterate<T, F> where
@@ -2853,7 +2853,7 @@ pub fn iterate<T, F>(seed: T, f: F) -> Iterate<T, F> where
     Unfold::new((f, Some(seed), true), next)
 }
 
-/// Create a new iterator that endlessly repeats the element `elt`.
+/// Creates a new iterator that endlessly repeats the element `elt`.
 #[inline]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
@@ -2940,7 +2940,7 @@ pub mod order {
         }
     }
 
-    /// Compare `a` and `b` for nonequality (Using partial equality, `PartialEq`)
+    /// Compares `a` and `b` for nonequality (Using partial equality, `PartialEq`)
     pub fn ne<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
         L::Item: PartialEq<R::Item>,
     {
@@ -2953,7 +2953,7 @@ pub mod order {
         }
     }
 
-    /// Return `a` < `b` lexicographically (Using partial order, `PartialOrd`)
+    /// Returns `a` < `b` lexicographically (Using partial order, `PartialOrd`)
     pub fn lt<R: Iterator, L: Iterator>(mut a: L, mut b: R) -> bool where
         L::Item: PartialOrd<R::Item>,
     {
@@ -2967,7 +2967,7 @@ pub mod order {
         }
     }
 
-    /// Return `a` <= `b` lexicographically (Using partial order, `PartialOrd`)
+    /// Returns `a` <= `b` lexicographically (Using partial order, `PartialOrd`)
     pub fn le<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
         L::Item: PartialOrd<R::Item>,
     {
@@ -2981,7 +2981,7 @@ pub mod order {
         }
     }
 
-    /// Return `a` > `b` lexicographically (Using partial order, `PartialOrd`)
+    /// Returns `a` > `b` lexicographically (Using partial order, `PartialOrd`)
     pub fn gt<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
         L::Item: PartialOrd<R::Item>,
     {
@@ -2995,7 +2995,7 @@ pub mod order {
         }
     }
 
-    /// Return `a` >= `b` lexicographically (Using partial order, `PartialOrd`)
+    /// Returns `a` >= `b` lexicographically (Using partial order, `PartialOrd`)
     pub fn ge<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
         L::Item: PartialOrd<R::Item>,
     {
diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs
index 249beb6295c..c4128e79765 100644
--- a/src/libcore/mem.rs
+++ b/src/libcore/mem.rs
@@ -134,7 +134,7 @@ pub fn align_of_val<T>(_val: &T) -> usize {
     align_of::<T>()
 }
 
-/// Create a value initialized to zero.
+/// Creates a value initialized to zero.
 ///
 /// This function is similar to allocating space for a local variable and zeroing it out (an unsafe
 /// operation).
@@ -158,7 +158,7 @@ pub unsafe fn zeroed<T>() -> T {
     intrinsics::init()
 }
 
-/// Create a value initialized to an unspecified series of bytes.
+/// Creates a value initialized to an unspecified series of bytes.
 ///
 /// The byte sequence usually indicates that the value at the memory
 /// in question has been dropped. Thus, *if* T carries a drop flag,
@@ -179,7 +179,7 @@ pub unsafe fn dropped<T>() -> T {
     dropped_impl()
 }
 
-/// Create an uninitialized value.
+/// Creates an uninitialized value.
 ///
 /// Care must be taken when using this function, if the type `T` has a destructor and the value
 /// falls out of scope (due to unwinding or returning) before being initialized, then the
@@ -234,7 +234,7 @@ pub fn swap<T>(x: &mut T, y: &mut T) {
     }
 }
 
-/// Replace the value at a mutable location with a new one, returning the old value, without
+/// Replaces the value at a mutable location with a new one, returning the old value, without
 /// deinitialising or copying either one.
 ///
 /// This is primarily used for transferring and swapping ownership of a value in a mutable
diff --git a/src/libcore/nonzero.rs b/src/libcore/nonzero.rs
index 3df4d00f60c..db2d1b2f1fd 100644
--- a/src/libcore/nonzero.rs
+++ b/src/libcore/nonzero.rs
@@ -38,7 +38,7 @@ unsafe impl Zeroable for u64 {}
 pub struct NonZero<T: Zeroable>(T);
 
 impl<T: Zeroable> NonZero<T> {
-    /// Create an instance of NonZero with the provided value.
+    /// Creates an instance of NonZero with the provided value.
     /// You must indeed ensure that the value is actually "non-zero".
     #[inline(always)]
     pub unsafe fn new(inner: T) -> NonZero<T> {
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 3fd179cf86f..9b1a384a0d0 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -268,7 +268,7 @@ pub trait Int
     #[stable(feature = "rust1", since = "1.0.0")]
     fn swap_bytes(self) -> Self;
 
-    /// Convert an integer from big endian to the target's endianness.
+    /// Converts an integer from big endian to the target's endianness.
     ///
     /// On big endian this is a no-op. On little endian the bytes are swapped.
     ///
@@ -291,7 +291,7 @@ pub trait Int
         if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
     }
 
-    /// Convert an integer from little endian to the target's endianness.
+    /// Converts an integer from little endian to the target's endianness.
     ///
     /// On little endian this is a no-op. On big endian the bytes are swapped.
     ///
@@ -314,7 +314,7 @@ pub trait Int
         if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
     }
 
-    /// Convert `self` to big endian from the target's endianness.
+    /// Converts `self` to big endian from the target's endianness.
     ///
     /// On big endian this is a no-op. On little endian the bytes are swapped.
     ///
@@ -337,7 +337,7 @@ pub trait Int
         if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
     }
 
-    /// Convert `self` to little endian from the target's endianness.
+    /// Converts `self` to little endian from the target's endianness.
     ///
     /// On little endian this is a no-op. On big endian the bytes are swapped.
     ///
@@ -845,7 +845,7 @@ macro_rules! int_impl {
             let min: $T = Int::min_value(); !min
         }
 
-        /// Convert a string slice in a given base to an integer.
+        /// Converts a string slice in a given base to an integer.
         ///
         /// Leading and trailing whitespace represent an error.
         ///
@@ -995,7 +995,7 @@ macro_rules! int_impl {
             (self as $UnsignedT).swap_bytes() as $T
         }
 
-        /// Convert an integer from big endian to the target's endianness.
+        /// Converts an integer from big endian to the target's endianness.
         ///
         /// On big endian this is a no-op. On little endian the bytes are
         /// swapped.
@@ -1019,7 +1019,7 @@ macro_rules! int_impl {
             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
         }
 
-        /// Convert an integer from little endian to the target's endianness.
+        /// Converts an integer from little endian to the target's endianness.
         ///
         /// On little endian this is a no-op. On big endian the bytes are
         /// swapped.
@@ -1043,7 +1043,7 @@ macro_rules! int_impl {
             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
         }
 
-        /// Convert `self` to big endian from the target's endianness.
+        /// Converts `self` to big endian from the target's endianness.
         ///
         /// On big endian this is a no-op. On little endian the bytes are
         /// swapped.
@@ -1067,7 +1067,7 @@ macro_rules! int_impl {
             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
         }
 
-        /// Convert `self` to little endian from the target's endianness.
+        /// Converts `self` to little endian from the target's endianness.
         ///
         /// On little endian this is a no-op. On big endian the bytes are
         /// swapped.
@@ -1361,7 +1361,7 @@ macro_rules! uint_impl {
         #[stable(feature = "rust1", since = "1.0.0")]
         pub fn max_value() -> $T { !0 }
 
-        /// Convert a string slice in a given base to an integer.
+        /// Converts a string slice in a given base to an integer.
         ///
         /// Leading and trailing whitespace represent an error.
         ///
@@ -1517,7 +1517,7 @@ macro_rules! uint_impl {
             unsafe { $bswap(self as $ActualT) as $T }
         }
 
-        /// Convert an integer from big endian to the target's endianness.
+        /// Converts an integer from big endian to the target's endianness.
         ///
         /// On big endian this is a no-op. On little endian the bytes are
         /// swapped.
@@ -1541,7 +1541,7 @@ macro_rules! uint_impl {
             if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
         }
 
-        /// Convert an integer from little endian to the target's endianness.
+        /// Converts an integer from little endian to the target's endianness.
         ///
         /// On little endian this is a no-op. On big endian the bytes are
         /// swapped.
@@ -1565,7 +1565,7 @@ macro_rules! uint_impl {
             if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
         }
 
-        /// Convert `self` to big endian from the target's endianness.
+        /// Converts `self` to big endian from the target's endianness.
         ///
         /// On big endian this is a no-op. On little endian the bytes are
         /// swapped.
@@ -1589,7 +1589,7 @@ macro_rules! uint_impl {
             if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
         }
 
-        /// Convert `self` to little endian from the target's endianness.
+        /// Converts `self` to little endian from the target's endianness.
         ///
         /// On little endian this is a no-op. On big endian the bytes are
         /// swapped.
@@ -2183,7 +2183,7 @@ impl_to_primitive_float! { f64 }
 /// A generic trait for converting a number to a value.
 #[unstable(feature = "core", reason = "trait is likely to be removed")]
 pub trait FromPrimitive : ::marker::Sized {
-    /// Convert an `isize` to return an optional value of this type. If the
+    /// Converts an `isize` to return an optional value of this type. If the
     /// value cannot be represented by this value, the `None` is returned.
     #[inline]
     #[unstable(feature = "core")]
@@ -2192,39 +2192,39 @@ pub trait FromPrimitive : ::marker::Sized {
         FromPrimitive::from_i64(n as i64)
     }
 
-    /// Convert an `isize` to return an optional value of this type. If the
+    /// Converts an `isize` to return an optional value of this type. If the
     /// value cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_isize(n: isize) -> Option<Self> {
         FromPrimitive::from_i64(n as i64)
     }
 
-    /// Convert an `i8` to return an optional value of this type. If the
+    /// Converts an `i8` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_i8(n: i8) -> Option<Self> {
         FromPrimitive::from_i64(n as i64)
     }
 
-    /// Convert an `i16` to return an optional value of this type. If the
+    /// Converts an `i16` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_i16(n: i16) -> Option<Self> {
         FromPrimitive::from_i64(n as i64)
     }
 
-    /// Convert an `i32` to return an optional value of this type. If the
+    /// Converts an `i32` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_i32(n: i32) -> Option<Self> {
         FromPrimitive::from_i64(n as i64)
     }
 
-    /// Convert an `i64` to return an optional value of this type. If the
+    /// Converts an `i64` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     fn from_i64(n: i64) -> Option<Self>;
 
-    /// Convert an `usize` to return an optional value of this type. If the
+    /// Converts an `usize` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     #[unstable(feature = "core")]
@@ -2233,46 +2233,46 @@ pub trait FromPrimitive : ::marker::Sized {
         FromPrimitive::from_u64(n as u64)
     }
 
-    /// Convert a `usize` to return an optional value of this type. If the
+    /// Converts a `usize` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_usize(n: usize) -> Option<Self> {
         FromPrimitive::from_u64(n as u64)
     }
 
-    /// Convert an `u8` to return an optional value of this type. If the
+    /// Converts an `u8` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_u8(n: u8) -> Option<Self> {
         FromPrimitive::from_u64(n as u64)
     }
 
-    /// Convert an `u16` to return an optional value of this type. If the
+    /// Converts an `u16` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_u16(n: u16) -> Option<Self> {
         FromPrimitive::from_u64(n as u64)
     }
 
-    /// Convert an `u32` to return an optional value of this type. If the
+    /// Converts an `u32` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_u32(n: u32) -> Option<Self> {
         FromPrimitive::from_u64(n as u64)
     }
 
-    /// Convert an `u64` to return an optional value of this type. If the
+    /// Converts an `u64` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     fn from_u64(n: u64) -> Option<Self>;
 
-    /// Convert a `f32` to return an optional value of this type. If the
+    /// Converts a `f32` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_f32(n: f32) -> Option<Self> {
         FromPrimitive::from_f64(n as f64)
     }
 
-    /// Convert a `f64` to return an optional value of this type. If the
+    /// Converts a `f64` to return an optional value of this type. If the
     /// type cannot be represented by this value, the `None` is returned.
     #[inline]
     fn from_f64(n: f64) -> Option<Self> {
@@ -2401,7 +2401,7 @@ impl_from_primitive! { u64, to_u64 }
 impl_from_primitive! { f32, to_f32 }
 impl_from_primitive! { f64, to_f64 }
 
-/// Cast from one machine scalar to another.
+/// Casts from one machine scalar to another.
 ///
 /// # Examples
 ///
@@ -2583,16 +2583,16 @@ pub trait Float
     /// Returns the mantissa, exponent and sign as integers, respectively.
     fn integer_decode(self) -> (u64, i16, i8);
 
-    /// Return the largest integer less than or equal to a number.
+    /// Returns the largest integer less than or equal to a number.
     fn floor(self) -> Self;
-    /// Return the smallest integer greater than or equal to a number.
+    /// Returns the smallest integer greater than or equal to a number.
     fn ceil(self) -> Self;
-    /// Return the nearest integer to a number. Round half-way cases away from
+    /// Returns the nearest integer to a number. Round half-way cases away from
     /// `0.0`.
     fn round(self) -> Self;
-    /// Return the integer part of a number.
+    /// Returns the integer part of a number.
     fn trunc(self) -> Self;
-    /// Return the fractional part of a number.
+    /// Returns the fractional part of a number.
     fn fract(self) -> Self;
 
     /// Computes the absolute value of `self`. Returns `Float::nan()` if the
@@ -2615,21 +2615,21 @@ pub trait Float
     /// error. This produces a more accurate result with better performance than
     /// a separate multiplication operation followed by an add.
     fn mul_add(self, a: Self, b: Self) -> Self;
-    /// Take the reciprocal (inverse) of a number, `1/x`.
+    /// Takes the reciprocal (inverse) of a number, `1/x`.
     fn recip(self) -> Self;
 
-    /// Raise a number to an integer power.
+    /// Raises a number to an integer power.
     ///
     /// Using this function is generally faster than using `powf`
     fn powi(self, n: i32) -> Self;
-    /// Raise a number to a floating point power.
+    /// Raises a number to a floating point power.
     fn powf(self, n: Self) -> Self;
 
-    /// Take the square root of a number.
+    /// Takes the square root of a number.
     ///
     /// Returns NaN if `self` is a negative number.
     fn sqrt(self) -> Self;
-    /// Take the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
+    /// Takes the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
     fn rsqrt(self) -> Self;
 
     /// Returns `e^(self)`, (the exponential function).
@@ -2645,9 +2645,9 @@ pub trait Float
     /// Returns the base 10 logarithm of the number.
     fn log10(self) -> Self;
 
-    /// Convert radians to degrees.
+    /// Converts radians to degrees.
     fn to_degrees(self) -> Self;
-    /// Convert degrees to radians.
+    /// Converts degrees to radians.
     fn to_radians(self) -> Self;
 }
 
@@ -2682,7 +2682,7 @@ macro_rules! from_str_radix_float_impl {
         impl FromStr for $T {
             type Err = ParseFloatError;
 
-            /// Convert a string in base 10 to a float.
+            /// Converts a string in base 10 to a float.
             /// Accepts an optional decimal exponent.
             ///
             /// This function accepts strings such as
@@ -2719,7 +2719,7 @@ macro_rules! from_str_radix_float_impl {
         impl FromStrRadix for $T {
             type Err = ParseFloatError;
 
-            /// Convert a string in a given base to a float.
+            /// Converts a string in a given base to a float.
             ///
             /// Due to possible conflicts, this function does **not** accept
             /// the special values `inf`, `-inf`, `+inf` and `NaN`, **nor**
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index 6db7c9bd99d..4c784a579da 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -223,7 +223,7 @@ impl<T> Option<T> {
     // Adapter for working with references
     /////////////////////////////////////////////////////////////////////////
 
-    /// Convert from `Option<T>` to `Option<&T>`
+    /// Converts from `Option<T>` to `Option<&T>`
     ///
     /// # Examples
     ///
@@ -248,7 +248,7 @@ impl<T> Option<T> {
         }
     }
 
-    /// Convert from `Option<T>` to `Option<&mut T>`
+    /// Converts from `Option<T>` to `Option<&mut T>`
     ///
     /// # Examples
     ///
@@ -269,7 +269,7 @@ impl<T> Option<T> {
         }
     }
 
-    /// Convert from `Option<T>` to `&mut [T]` (without copying)
+    /// Converts from `Option<T>` to `&mut [T]` (without copying)
     ///
     /// # Examples
     ///
@@ -704,7 +704,7 @@ impl<T> Option<T> {
         mem::replace(self, None)
     }
 
-    /// Convert from `Option<T>` to `&[T]` (without copying)
+    /// Converts from `Option<T>` to `&[T]` (without copying)
     #[inline]
     #[unstable(feature = "as_slice", since = "unsure of the utility here")]
     pub fn as_slice<'a>(&'a self) -> &'a [T] {
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index a622ef78a21..9a165a2e317 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -544,19 +544,19 @@ unsafe impl<T: Send + ?Sized> Send for Unique<T> { }
 unsafe impl<T: Sync + ?Sized> Sync for Unique<T> { }
 
 impl<T: ?Sized> Unique<T> {
-    /// Create a new `Unique`.
+    /// Creates a new `Unique`.
     #[unstable(feature = "unique")]
     pub unsafe fn new(ptr: *mut T) -> Unique<T> {
         Unique { pointer: NonZero::new(ptr), _marker: PhantomData }
     }
 
-    /// Dereference the content.
+    /// Dereferences the content.
     #[unstable(feature = "unique")]
     pub unsafe fn get(&self) -> &T {
         &**self.pointer
     }
 
-    /// Mutably dereference the content.
+    /// Mutably dereferences the content.
     #[unstable(feature = "unique")]
     pub unsafe fn get_mut(&mut self) -> &mut T {
         &mut ***self
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index 67a5ab891f7..4c74f4646ac 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -69,7 +69,7 @@
 //! let good_result: Result<bool, i32> = good_result.and_then(|i| Ok(i == 11));
 //!
 //! // Use `or_else` to handle the error.
-//! let bad_result: Result<i32, i32> = bad_result.or_else(|i| Ok(11));
+//! let bad_result: Result<i32, i32> = bad_result.or_else(|i| Ok(i + 20));
 //!
 //! // Consume the result and return the contents with `unwrap`.
 //! let final_awesome_result = good_result.unwrap();
@@ -85,35 +85,32 @@
 //! functions that may encounter errors but don't otherwise return a
 //! useful value.
 //!
-//! Consider the `write_line` method defined for I/O types
-//! by the [`Writer`](../old_io/trait.Writer.html) trait:
+//! Consider the `write_all` method defined for I/O types
+//! by the [`Write`](../io/trait.Write.html) trait:
 //!
 //! ```
-//! # #![feature(old_io)]
-//! use std::old_io::IoError;
+//! use std::io;
 //!
 //! trait Writer {
-//!     fn write_line(&mut self, s: &str) -> Result<(), IoError>;
+//!     fn write_all(&mut self, bytes: &[u8]) -> Result<(), io::Error>;
 //! }
 //! ```
 //!
-//! *Note: The actual definition of `Writer` uses `IoResult`, which
-//! is just a synonym for `Result<T, IoError>`.*
+//! *Note: The actual definition of `Write` uses `io::Result`, which
+//! is just a synonym for `Result<T, io::Error>`.*
 //!
 //! This method doesn't produce a value, but the write may
 //! fail. It's crucial to handle the error case, and *not* write
 //! something like this:
 //!
-//! ```{.ignore}
-//! # #![feature(old_io)]
-//! use std::old_io::*;
-//! use std::old_path::Path;
+//! ```no_run
+//! use std::fs::File;
+//! use std::io::prelude::*;
 //!
-//! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
-//! // If `write_line` errors, then we'll never know, because the return
+//! let mut file = File::create("valuable_data.txt").unwrap();
+//! // If `write_all` errors, then we'll never know, because the return
 //! // value is ignored.
-//! file.write_line("important message");
-//! drop(file);
+//! file.write_all(b"important message");
 //! ```
 //!
 //! If you *do* write that in Rust, the compiler will give you a
@@ -125,37 +122,31 @@
 //! a marginally useful message indicating why:
 //!
 //! ```{.no_run}
-//! # #![feature(old_io, old_path)]
-//! use std::old_io::*;
-//! use std::old_path::Path;
+//! use std::fs::File;
+//! use std::io::prelude::*;
 //!
-//! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
-//! file.write_line("important message").ok().expect("failed to write message");
-//! drop(file);
+//! let mut file = File::create("valuable_data.txt").unwrap();
+//! file.write_all(b"important message").ok().expect("failed to write message");
 //! ```
 //!
 //! You might also simply assert success:
 //!
 //! ```{.no_run}
-//! # #![feature(old_io, old_path)]
-//! # use std::old_io::*;
-//! # use std::old_path::Path;
-//!
-//! # let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
-//! assert!(file.write_line("important message").is_ok());
-//! # drop(file);
+//! # use std::fs::File;
+//! # use std::io::prelude::*;
+//! # let mut file = File::create("valuable_data.txt").unwrap();
+//! assert!(file.write_all(b"important message").is_ok());
 //! ```
 //!
 //! Or propagate the error up the call stack with `try!`:
 //!
 //! ```
-//! # #![feature(old_io, old_path)]
-//! # use std::old_io::*;
-//! # use std::old_path::Path;
-//! fn write_message() -> Result<(), IoError> {
-//!     let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
-//!     try!(file.write_line("important message"));
-//!     drop(file);
+//! # use std::fs::File;
+//! # use std::io::prelude::*;
+//! # use std::io;
+//! fn write_message() -> io::Result<()> {
+//!     let mut file = try!(File::create("valuable_data.txt"));
+//!     try!(file.write_all(b"important message"));
 //!     Ok(())
 //! }
 //! ```
@@ -170,9 +161,9 @@
 //! It replaces this:
 //!
 //! ```
-//! # #![feature(old_io, old_path)]
-//! use std::old_io::*;
-//! use std::old_path::Path;
+//! use std::fs::File;
+//! use std::io::prelude::*;
+//! use std::io;
 //!
 //! struct Info {
 //!     name: String,
@@ -180,25 +171,28 @@
 //!     rating: i32,
 //! }
 //!
-//! fn write_info(info: &Info) -> Result<(), IoError> {
-//!     let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write);
+//! fn write_info(info: &Info) -> io::Result<()> {
+//!     let mut file = try!(File::create("my_best_friends.txt"));
 //!     // Early return on error
-//!     if let Err(e) = file.write_line(&format!("name: {}", info.name)) {
+//!     if let Err(e) = file.write_all(format!("name: {}\n", info.name).as_bytes()) {
+//!         return Err(e)
+//!     }
+//!     if let Err(e) = file.write_all(format!("age: {}\n", info.age).as_bytes()) {
 //!         return Err(e)
 //!     }
-//!     if let Err(e) = file.write_line(&format!("age: {}", info.age)) {
+//!     if let Err(e) = file.write_all(format!("rating: {}\n", info.rating).as_bytes()) {
 //!         return Err(e)
 //!     }
-//!     file.write_line(&format!("rating: {}", info.rating))
+//!     Ok(())
 //! }
 //! ```
 //!
 //! With this:
 //!
 //! ```
-//! # #![feature(old_io, old_path)]
-//! use std::old_io::*;
-//! use std::old_path::Path;
+//! use std::fs::File;
+//! use std::io::prelude::*;
+//! use std::io;
 //!
 //! struct Info {
 //!     name: String,
@@ -206,12 +200,12 @@
 //!     rating: i32,
 //! }
 //!
-//! fn write_info(info: &Info) -> Result<(), IoError> {
-//!     let mut file = File::open_mode(&Path::new("my_best_friends.txt"), Open, Write);
+//! fn write_info(info: &Info) -> io::Result<()> {
+//!     let mut file = try!(File::create("my_best_friends.txt"));
 //!     // Early return on error
-//!     try!(file.write_line(&format!("name: {}", info.name)));
-//!     try!(file.write_line(&format!("age: {}", info.age)));
-//!     try!(file.write_line(&format!("rating: {}", info.rating)));
+//!     try!(file.write_all(format!("name: {}\n", info.name).as_bytes()));
+//!     try!(file.write_all(format!("age: {}\n", info.age).as_bytes()));
+//!     try!(file.write_all(format!("rating: {}\n", info.rating).as_bytes()));
 //!     Ok(())
 //! }
 //! ```
@@ -311,7 +305,7 @@ impl<T, E> Result<T, E> {
     // Adapter for each variant
     /////////////////////////////////////////////////////////////////////////
 
-    /// Convert from `Result<T, E>` to `Option<T>`
+    /// Converts from `Result<T, E>` to `Option<T>`
     ///
     /// Converts `self` into an `Option<T>`, consuming `self`,
     /// and discarding the error, if any.
@@ -334,7 +328,7 @@ impl<T, E> Result<T, E> {
         }
     }
 
-    /// Convert from `Result<T, E>` to `Option<E>`
+    /// Converts from `Result<T, E>` to `Option<E>`
     ///
     /// Converts `self` into an `Option<E>`, consuming `self`,
     /// and discarding the success value, if any.
@@ -361,7 +355,7 @@ impl<T, E> Result<T, E> {
     // Adapter for working with references
     /////////////////////////////////////////////////////////////////////////
 
-    /// Convert from `Result<T, E>` to `Result<&T, &E>`
+    /// Converts from `Result<T, E>` to `Result<&T, &E>`
     ///
     /// Produces a new `Result`, containing a reference
     /// into the original, leaving the original in place.
@@ -382,7 +376,7 @@ impl<T, E> Result<T, E> {
         }
     }
 
-    /// Convert from `Result<T, E>` to `Result<&mut T, &mut E>`
+    /// Converts from `Result<T, E>` to `Result<&mut T, &mut E>`
     ///
     /// ```
     /// fn mutate(r: &mut Result<i32, i32>) {
@@ -409,7 +403,7 @@ impl<T, E> Result<T, E> {
         }
     }
 
-    /// Convert from `Result<T, E>` to `&[T]` (without copying)
+    /// Converts from `Result<T, E>` to `&[T]` (without copying)
     #[inline]
     #[unstable(feature = "as_slice", since = "unsure of the utility here")]
     pub fn as_slice(&self) -> &[T] {
@@ -423,7 +417,7 @@ impl<T, E> Result<T, E> {
         }
     }
 
-    /// Convert from `Result<T, E>` to `&mut [T]` (without copying)
+    /// Converts from `Result<T, E>` to `&mut [T]` (without copying)
     ///
     /// ```
     /// # #![feature(core)]
@@ -464,29 +458,17 @@ impl<T, E> Result<T, E> {
     ///
     /// # Examples
     ///
-    /// Sum the lines of a buffer by mapping strings to numbers,
-    /// ignoring I/O and parse errors:
+    /// Print the numbers on each line of a string multiplied by two.
     ///
     /// ```
-    /// # #![feature(old_io)]
-    /// use std::old_io::*;
+    /// let line = "1\n2\n3\n4\n";
     ///
-    /// let mut buffer: &[u8] = b"1\n2\n3\n4\n";
-    /// let mut buffer = &mut buffer;
-    ///
-    /// let mut sum = 0;
-    ///
-    /// while !buffer.is_empty() {
-    ///     let line: IoResult<String> = buffer.read_line();
-    ///     // Convert the string line to a number using `map` and `from_str`
-    ///     let val: IoResult<i32> = line.map(|line| {
-    ///         line.trim_right().parse::<i32>().unwrap_or(0)
-    ///     });
-    ///     // Add the value if there were no errors, otherwise add 0
-    ///     sum += val.unwrap_or(0);
+    /// for num in line.lines() {
+    ///     match num.parse::<i32>().map(|i| i * 2) {
+    ///         Ok(n) => println!("{}", n),
+    ///         Err(..) => {}
+    ///     }
     /// }
-    ///
-    /// assert!(sum == 10);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
@@ -811,7 +793,7 @@ impl<T: fmt::Debug, E> Result<T, E> {
              reason = "use inherent method instead")]
 #[allow(deprecated)]
 impl<T, E> AsSlice<T> for Result<T, E> {
-    /// Convert from `Result<T, E>` to `&[T]` (without copying)
+    /// Converts from `Result<T, E>` to `&[T]` (without copying)
     #[inline]
     fn as_slice<'a>(&'a self) -> &'a [T] {
         match *self {
@@ -974,7 +956,7 @@ impl<A, E, V: FromIterator<A>> FromIterator<Result<A, E>> for Result<V, E> {
 // FromIterator
 /////////////////////////////////////////////////////////////////////////////
 
-/// Perform a fold operation over the result values from an iterator.
+/// Performs a fold operation over the result values from an iterator.
 ///
 /// If an `Err` is encountered, it is immediately returned.
 /// Otherwise, the folded value is returned.
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 9bc760b56ec..fc623f21167 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -106,19 +106,19 @@ Section: Creating a string
 
 /// Errors which can occur when attempting to interpret a byte slice as a `str`.
 #[derive(Copy, Eq, PartialEq, Clone, Debug)]
-#[unstable(feature = "core",
-           reason = "error enumeration recently added and definitions may be refined")]
-pub enum Utf8Error {
-    /// An invalid byte was detected at the byte offset given.
-    ///
-    /// The offset is guaranteed to be in bounds of the slice in question, and
-    /// the byte at the specified offset was the first invalid byte in the
-    /// sequence detected.
-    InvalidByte(usize),
+#[stable(feature = "rust1", since = "1.0.0")]
+pub struct Utf8Error {
+    valid_up_to: usize,
+}
 
-    /// The byte slice was invalid because more bytes were needed but no more
-    /// bytes were available.
-    TooShort,
+impl Utf8Error {
+    /// Returns the index in the given string up to which valid UTF-8 was
+    /// verified.
+    ///
+    /// Starting at the index provided, but not necessarily at it precisely, an
+    /// invalid UTF-8 encoding sequence was found.
+    #[unstable(feature = "utf8_error", reason = "method just added")]
+    pub fn valid_up_to(&self) -> usize { self.valid_up_to }
 }
 
 /// Converts a slice of bytes to a string slice without performing any
@@ -147,14 +147,7 @@ pub unsafe fn from_utf8_unchecked<'a>(v: &'a [u8]) -> &'a str {
 #[stable(feature = "rust1", since = "1.0.0")]
 impl fmt::Display for Utf8Error {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        match *self {
-            Utf8Error::InvalidByte(n) => {
-                write!(f, "invalid utf-8: invalid byte at index {}", n)
-            }
-            Utf8Error::TooShort => {
-                write!(f, "invalid utf-8: byte slice too short")
-            }
-        }
+        write!(f, "invalid utf-8: invalid byte near index {}", self.valid_up_to)
     }
 }
 
@@ -1218,14 +1211,16 @@ fn run_utf8_validation_iterator(iter: &mut slice::Iter<u8>)
         // restore the iterator we had at the start of this codepoint.
         macro_rules! err { () => {{
             *iter = old.clone();
-            return Err(Utf8Error::InvalidByte(whole.len() - iter.as_slice().len()))
+            return Err(Utf8Error {
+                valid_up_to: whole.len() - iter.as_slice().len()
+            })
         }}}
 
         macro_rules! next { () => {
             match iter.next() {
                 Some(a) => *a,
                 // we needed data, but there was none: error!
-                None => return Err(Utf8Error::TooShort),
+                None => err!(),
             }
         }}
 
diff --git a/src/libcore/str/pattern.rs b/src/libcore/str/pattern.rs
index 9f701e1b031..62b693dcbe6 100644
--- a/src/libcore/str/pattern.rs
+++ b/src/libcore/str/pattern.rs
@@ -32,17 +32,17 @@ pub trait Pattern<'a>: Sized {
     /// Associated searcher for this pattern
     type Searcher: Searcher<'a>;
 
-    /// Construct the associated searcher from
+    /// Constructs the associated searcher from
     /// `self` and the `haystack` to search in.
     fn into_searcher(self, haystack: &'a str) -> Self::Searcher;
 
-    /// Check whether the pattern matches anywhere in the haystack
+    /// Checks whether the pattern matches anywhere in the haystack
     #[inline]
     fn is_contained_in(self, haystack: &'a str) -> bool {
         self.into_searcher(haystack).next_match().is_some()
     }
 
-    /// Check whether the pattern matches at the front of the haystack
+    /// Checks whether the pattern matches at the front of the haystack
     #[inline]
     fn is_prefix_of(self, haystack: &'a str) -> bool {
         match self.into_searcher(haystack).next() {
@@ -51,7 +51,7 @@ pub trait Pattern<'a>: Sized {
         }
     }
 
-    /// Check whether the pattern matches at the back of the haystack
+    /// Checks whether the pattern matches at the back of the haystack
     #[inline]
     fn is_suffix_of(self, haystack: &'a str) -> bool
         where Self::Searcher: ReverseSearcher<'a>