Merge remote-tracking branch 'rust-lang/master'

Conflicts:
	src/libcore/cell.rs
	src/librustc_driver/test.rs
	src/libstd/old_io/net/tcp.rs
	src/libstd/old_io/process.rs

4 files changed, 220 insertions, 95 deletions

diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index ddcc41938f2..02cc4038a69 100644
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -10,39 +10,30 @@
 
 //! Shareable mutable containers.
 //!
-//! Values of the `Cell` and `RefCell` types may be mutated through
-//! shared references (i.e. the common `&T` type), whereas most Rust
-//! types can only be mutated through unique (`&mut T`) references. We
-//! say that `Cell` and `RefCell` provide *interior mutability*, in
-//! contrast with typical Rust types that exhibit *inherited
-//! mutability*.
+//! Values of the `Cell<T>` and `RefCell<T>` types may be mutated through shared references (i.e.
+//! the common `&T` type), whereas most Rust types can only be mutated through unique (`&mut T`)
+//! references. We say that `Cell<T>` and `RefCell<T>` provide 'interior mutability', in contrast
+//! with typical Rust types that exhibit 'inherited mutability'.
 //!
-//! Cell types come in two flavors: `Cell` and `RefCell`. `Cell`
-//! provides `get` and `set` methods that change the
-//! interior value with a single method call. `Cell` though is only
-//! compatible with types that implement `Copy`. For other types,
-//! one must use the `RefCell` type, acquiring a write lock before
-//! mutating.
+//! Cell types come in two flavors: `Cell<T>` and `RefCell<T>`. `Cell<T>` provides `get` and `set`
+//! methods that change the interior value with a single method call. `Cell<T>` though is only
+//! compatible with types that implement `Copy`. For other types, one must use the `RefCell<T>`
+//! type, acquiring a write lock before mutating.
 //!
-//! `RefCell` uses Rust's lifetimes to implement *dynamic borrowing*,
-//! a process whereby one can claim temporary, exclusive, mutable
-//! access to the inner value. Borrows for `RefCell`s are tracked *at
-//! runtime*, unlike Rust's native reference types which are entirely
-//! tracked statically, at compile time. Because `RefCell` borrows are
-//! dynamic it is possible to attempt to borrow a value that is
-//! already mutably borrowed; when this happens it results in task
-//! panic.
+//! `RefCell<T>` uses Rust's lifetimes to implement 'dynamic borrowing', a process whereby one can
+//! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell<T>`s are
+//! tracked 'at runtime', unlike Rust's native reference types which are entirely tracked
+//! statically, at compile time. Because `RefCell<T>` borrows are dynamic it is possible to attempt
+//! to borrow a value that is already mutably borrowed; when this happens it results in task panic.
 //!
 //! # When to choose interior mutability
 //!
-//! The more common inherited mutability, where one must have unique
-//! access to mutate a value, is one of the key language elements that
-//! enables Rust to reason strongly about pointer aliasing, statically
-//! preventing crash bugs. Because of that, inherited mutability is
-//! preferred, and interior mutability is something of a last
-//! resort. Since cell types enable mutation where it would otherwise
-//! be disallowed though, there are occasions when interior
-//! mutability might be appropriate, or even *must* be used, e.g.
+//! The more common inherited mutability, where one must have unique access to mutate a value, is
+//! one of the key language elements that enables Rust to reason strongly about pointer aliasing,
+//! statically preventing crash bugs. Because of that, inherited mutability is preferred, and
+//! interior mutability is something of a last resort. Since cell types enable mutation where it
+//! would otherwise be disallowed though, there are occasions when interior mutability might be
+//! appropriate, or even *must* be used, e.g.
 //!
 //! * Introducing inherited mutability roots to shared types.
 //! * Implementation details of logically-immutable methods.
@@ -50,15 +41,13 @@
 //!
 //! ## Introducing inherited mutability roots to shared types
 //!
-//! Shared smart pointer types, including `Rc` and `Arc`, provide
-//! containers that can be cloned and shared between multiple parties.
-//! Because the contained values may be multiply-aliased, they can
-//! only be borrowed as shared references, not mutable references.
-//! Without cells it would be impossible to mutate data inside of
-//! shared boxes at all!
+//! Shared smart pointer types, including `Rc<T>` and `Arc<T>`, provide containers that can be
+//! cloned and shared between multiple parties. Because the contained values may be
+//! multiply-aliased, they can only be borrowed as shared references, not mutable references.
+//! Without cells it would be impossible to mutate data inside of shared boxes at all!
 //!
-//! It's very common then to put a `RefCell` inside shared pointer
-//! types to reintroduce mutability:
+//! It's very common then to put a `RefCell<T>` inside shared pointer types to reintroduce
+//! mutability:
 //!
 //! ```
 //! use std::collections::HashMap;
@@ -80,12 +69,10 @@
 //!
 //! ## Implementation details of logically-immutable methods
 //!
-//! Occasionally it may be desirable not to expose in an API that
-//! there is mutation happening "under the hood". This may be because
-//! logically the operation is immutable, but e.g. caching forces the
-//! implementation to perform mutation; or because you must employ
-//! mutation to implement a trait method that was originally defined
-//! to take `&self`.
+//! Occasionally it may be desirable not to expose in an API that there is mutation happening
+//! "under the hood". This may be because logically the operation is immutable, but e.g. caching
+//! forces the implementation to perform mutation; or because you must employ mutation to implement
+//! a trait method that was originally defined to take `&self`.
 //!
 //! ```
 //! use std::cell::RefCell;
@@ -123,13 +110,11 @@
 //!
 //! ## Mutating implementations of `clone`
 //!
-//! This is simply a special - but common - case of the previous:
-//! hiding mutability for operations that appear to be immutable.
-//! The `clone` method is expected to not change the source value, and
-//! is declared to take `&self`, not `&mut self`. Therefore any
-//! mutation that happens in the `clone` method must use cell
-//! types. For example, `Rc` maintains its reference counts within a
-//! `Cell`.
+//! This is simply a special - but common - case of the previous: hiding mutability for operations
+//! that appear to be immutable. The `clone` method is expected to not change the source value, and
+//! is declared to take `&self`, not `&mut self`. Therefore any mutation that happens in the
+//! `clone` method must use cell types. For example, `Rc<T>` maintains its reference counts within a
+//! `Cell<T>`.
 //!
 //! ```
 //! use std::cell::Cell;
@@ -153,10 +138,6 @@
 //! }
 //! ```
 //!
-// FIXME: Explain difference between Cell and RefCell
-// FIXME: Downsides to interior mutability
-// FIXME: Can't be shared between threads. Dynamic borrows
-// FIXME: Relationship to Atomic types and RWLock
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -169,6 +150,8 @@ use option::Option;
 use option::Option::{None, Some};
 
 /// A mutable memory location that admits only `Copy` data.
+///
+/// See the [module-level documentation](../index.html) for more.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Cell<T> {
     value: UnsafeCell<T>,
@@ -176,6 +159,14 @@ pub struct Cell<T> {
 
 impl<T:Copy> Cell<T> {
     /// Creates a new `Cell` containing the given value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn new(value: T) -> Cell<T> {
         Cell {
@@ -184,6 +175,16 @@ impl<T:Copy> Cell<T> {
     }
 
     /// Returns a copy of the contained value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    ///
+    /// let five = c.get();
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn get(&self) -> T {
@@ -191,6 +192,16 @@ impl<T:Copy> Cell<T> {
     }
 
     /// Sets the contained value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    ///
+    /// c.set(10);
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn set(&self, value: T) {
@@ -201,9 +212,19 @@ impl<T:Copy> Cell<T> {
 
     /// Get a reference to the underlying `UnsafeCell`.
     ///
-    /// This can be used to circumvent `Cell`'s safety checks.
+    /// # Unsafety
     ///
     /// This function is `unsafe` because `UnsafeCell`'s field is public.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::Cell;
+    ///
+    /// let c = Cell::new(5);
+    ///
+    /// let uc = unsafe { c.as_unsafe_cell() };
+    /// ```
     #[inline]
     #[unstable(feature = "core")]
     pub unsafe fn as_unsafe_cell<'a>(&'a self) -> &'a UnsafeCell<T> {
@@ -237,6 +258,8 @@ impl<T:PartialEq + Copy> PartialEq for Cell<T> {
 }
 
 /// A mutable memory location with dynamically checked borrow rules
+///
+/// See the [module-level documentation](../index.html) for more.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RefCell<T> {
     value: UnsafeCell<T>,
@@ -250,7 +273,15 @@ const UNUSED: BorrowFlag = 0;
 const WRITING: BorrowFlag = -1;
 
 impl<T> RefCell<T> {
-    /// Create a new `RefCell` containing `value`
+    /// Creates a new `RefCell` containing `value`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::RefCell;
+    ///
+    /// let c = RefCell::new(5);
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn new(value: T) -> RefCell<T> {
         RefCell {
@@ -260,6 +291,16 @@ impl<T> RefCell<T> {
     }
 
     /// Consumes the `RefCell`, returning the wrapped value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::RefCell;
+    ///
+    /// let c = RefCell::new(5);
+    ///
+    /// let five = c.into_inner();
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn into_inner(self) -> T {
         // Since this function takes `self` (the `RefCell`) by value, the
@@ -285,12 +326,39 @@ impl<T> RefCell<T> {
 
     /// Immutably borrows the wrapped value.
     ///
-    /// The borrow lasts until the returned `Ref` exits scope. Multiple
-    /// immutable borrows can be taken out at the same time.
+    /// The borrow lasts until the returned `Ref` exits scope. Multiple immutable borrows can be
+    /// taken out at the same time.
     ///
     /// # Panics
     ///
     /// Panics if the value is currently mutably borrowed.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::RefCell;
+    ///
+    /// let c = RefCell::new(5);
+    ///
+    /// let borrowed_five = c.borrow();
+    /// let borrowed_five2 = c.borrow();
+    /// ```
+    ///
+    /// An example of panic:
+    ///
+    /// ```
+    /// use std::cell::RefCell;
+    /// use std::thread::Thread;
+    ///
+    /// let result = Thread::scoped(move || {
+    ///    let c = RefCell::new(5);
+    ///    let m = c.borrow_mut();
+    ///
+    ///    let b = c.borrow(); // this causes a panic
+    /// }).join();
+    ///
+    /// assert!(result.is_err());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn borrow<'a>(&'a self) -> Ref<'a, T> {
         match self.try_borrow() {
@@ -315,12 +383,38 @@ impl<T> RefCell<T> {
 
     /// Mutably borrows the wrapped value.
     ///
-    /// The borrow lasts until the returned `RefMut` exits scope. The value
-    /// cannot be borrowed while this borrow is active.
+    /// The borrow lasts until the returned `RefMut` exits scope. The value cannot be borrowed
+    /// while this borrow is active.
     ///
     /// # Panics
     ///
     /// Panics if the value is currently borrowed.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::RefCell;
+    ///
+    /// let c = RefCell::new(5);
+    ///
+    /// let borrowed_five = c.borrow_mut();
+    /// ```
+    ///
+    /// An example of panic:
+    ///
+    /// ```
+    /// use std::cell::RefCell;
+    /// use std::thread::Thread;
+    ///
+    /// let result = Thread::scoped(move || {
+    ///    let c = RefCell::new(5);
+    ///    let m = c.borrow_mut();
+    ///
+    ///    let b = c.borrow_mut(); // this causes a panic
+    /// }).join();
+    ///
+    /// assert!(result.is_err());
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn borrow_mut<'a>(&'a self) -> RefMut<'a, T> {
         match self.try_borrow_mut() {
@@ -403,6 +497,9 @@ impl<'b> Clone for BorrowRef<'b> {
 }
 
 /// Wraps a borrowed reference to a value in a `RefCell` box.
+/// A wrapper type for an immutably borrowed value from a `RefCell<T>`.
+///
+/// See the [module-level documentation](../index.html) for more.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Ref<'b, T:'b> {
     // FIXME #12808: strange name to try to avoid interfering with
@@ -461,7 +558,9 @@ impl<'b> BorrowRefMut<'b> {
     }
 }
 
-/// Wraps a mutable borrowed reference to a value in a `RefCell` box.
+/// A wrapper type for a mutably borrowed value from a `RefCell<T>`.
+///
+/// See the [module-level documentation](../index.html) for more.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RefMut<'b, T:'b> {
     // FIXME #12808: strange name to try to avoid interfering with
@@ -490,28 +589,25 @@ impl<'b, T> DerefMut for RefMut<'b, T> {
 
 /// The core primitive for interior mutability in Rust.
 ///
-/// `UnsafeCell` type that wraps a type T and indicates unsafe interior
-/// operations on the wrapped type. Types with an `UnsafeCell<T>` field are
-/// considered to have an *unsafe interior*. The `UnsafeCell` type is the only
-/// legal way to obtain aliasable data that is considered mutable. In general,
-/// transmuting an &T type into an &mut T is considered undefined behavior.
+/// `UnsafeCell<T>` is a type that wraps some `T` and indicates unsafe interior operations on the
+/// wrapped type. Types with an `UnsafeCell<T>` field are considered to have an 'unsafe interior'.
+/// The `UnsafeCell<T>` type is the only legal way to obtain aliasable data that is considered
+/// mutable. In general, transmuting an `&T` type into an `&mut T` is considered undefined behavior.
 ///
-/// Although it is possible to put an `UnsafeCell<T>` into static item, it is
-/// not permitted to take the address of the static item if the item is not
-/// declared as mutable. This rule exists because immutable static items are
-/// stored in read-only memory, and thus any attempt to mutate their interior
-/// can cause segfaults. Immutable static items containing `UnsafeCell<T>`
-/// instances are still useful as read-only initializers, however, so we do not
-/// forbid them altogether.
+/// Although it is possible to put an `UnsafeCell<T>` into static item, it is not permitted to take
+/// the address of the static item if the item is not declared as mutable. This rule exists because
+/// immutable static items are stored in read-only memory, and thus any attempt to mutate their
+/// interior can cause segfaults. Immutable static items containing `UnsafeCell<T>` instances are
+/// still useful as read-only initializers, however, so we do not forbid them altogether.
 ///
-/// Types like `Cell` and `RefCell` use this type to wrap their internal data.
+/// Types like `Cell<T>` and `RefCell<T>` use this type to wrap their internal data.
 ///
-/// `UnsafeCell` doesn't opt-out from any kind, instead, types with an
-/// `UnsafeCell` interior are expected to opt-out from kinds themselves.
+/// `UnsafeCell<T>` doesn't opt-out from any marker traits, instead, types with an `UnsafeCell<T>`
+/// interior are expected to opt-out from those traits themselves.
 ///
-/// # Example:
+/// # Examples
 ///
-/// ```rust
+/// ```
 /// use std::cell::UnsafeCell;
 /// use std::marker::Sync;
 ///
@@ -522,9 +618,8 @@ impl<'b, T> DerefMut for RefMut<'b, T> {
 /// unsafe impl<T> Sync for NotThreadSafe<T> {}
 /// ```
 ///
-/// **NOTE:** `UnsafeCell<T>` fields are public to allow static initializers. It
-/// is not recommended to access its fields directly, `get` should be used
-/// instead.
+/// **NOTE:** `UnsafeCell<T>`'s fields are public to allow static initializers. It is not
+/// recommended to access its fields directly, `get` should be used instead.
 #[lang="unsafe"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct UnsafeCell<T> {
@@ -540,22 +635,52 @@ impl<T> UnsafeCell<T> {
     /// Construct 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 access the fields directly.
+    /// All access to the inner value through methods is `unsafe`, and it is highly discouraged to
+    /// access the fields directly.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::UnsafeCell;
+    ///
+    /// let uc = UnsafeCell::new(5);
+    /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn new(value: T) -> UnsafeCell<T> {
         UnsafeCell { value: value }
     }
 
     /// Gets a mutable pointer to the wrapped value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::UnsafeCell;
+    ///
+    /// let uc = UnsafeCell::new(5);
+    ///
+    /// let five = uc.get();
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn get(&self) -> *mut T { &self.value as *const T as *mut T }
 
     /// Unwraps the value
     ///
-    /// This function is unsafe because there is no guarantee that this or other
-    /// tasks are currently inspecting the inner value.
+    /// # Unsafety
+    ///
+    /// This function is unsafe because there is no guarantee that this or other threads are
+    /// currently inspecting the inner value.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::cell::UnsafeCell;
+    ///
+    /// let uc = UnsafeCell::new(5);
+    ///
+    /// let five = unsafe { uc.into_inner() };
+    /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub unsafe fn into_inner(self) -> T { self.value }
diff --git a/src/libcore/error.rs b/src/libcore/error.rs
index 9519539f000..71d5e88cccf 100644
--- a/src/libcore/error.rs
+++ b/src/libcore/error.rs
@@ -49,7 +49,7 @@
 //!
 //! ```
 //! use std::error::FromError;
-//! use std::io::{File, IoError};
+//! use std::old_io::{File, IoError};
 //! use std::os::{MemoryMap, MapError};
 //! use std::path::Path;
 //!
diff --git a/src/libcore/fmt/mod.rs b/src/libcore/fmt/mod.rs
index 8e6715fa38b..06428ad2f39 100644
--- a/src/libcore/fmt/mod.rs
+++ b/src/libcore/fmt/mod.rs
@@ -238,7 +238,7 @@ impl<'a> Display for Arguments<'a> {
     }
 }
 
-/// Format trait for the `:?` format. Useful for debugging, most all types
+/// Format trait for the `:?` format. Useful for debugging, all types
 /// should implement this.
 #[unstable(feature = "core",
            reason = "I/O and core have yet to be reconciled")]
@@ -249,7 +249,7 @@ pub trait Show {
     fn fmt(&self, &mut Formatter) -> Result;
 }
 
-/// Format trait for the `:?` format. Useful for debugging, most all types
+/// Format trait for the `:?` format. Useful for debugging, all types
 /// should implement this.
 #[unstable(feature = "core",
            reason = "I/O and core have yet to be reconciled")]
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index bfbc96c5a39..ade257165c6 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -95,7 +95,7 @@
 //! by the [`Writer`](../io/trait.Writer.html) trait:
 //!
 //! ```
-//! use std::io::IoError;
+//! use std::old_io::IoError;
 //!
 //! trait Writer {
 //!     fn write_line(&mut self, s: &str) -> Result<(), IoError>;
@@ -110,7 +110,7 @@
 //! something like this:
 //!
 //! ```{.ignore}
-//! use std::io::{File, Open, Write};
+//! use std::old_io::{File, Open, Write};
 //!
 //! 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
@@ -128,7 +128,7 @@
 //! a marginally useful message indicating why:
 //!
 //! ```{.no_run}
-//! use std::io::{File, Open, Write};
+//! use std::old_io::{File, Open, Write};
 //!
 //! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
 //! file.write_line("important message").ok().expect("failed to write message");
@@ -138,7 +138,7 @@
 //! You might also simply assert success:
 //!
 //! ```{.no_run}
-//! # use std::io::{File, Open, Write};
+//! # use std::old_io::{File, Open, Write};
 //!
 //! # let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
 //! assert!(file.write_line("important message").is_ok());
@@ -148,7 +148,7 @@
 //! Or propagate the error up the call stack with `try!`:
 //!
 //! ```
-//! # use std::io::{File, Open, Write, IoError};
+//! # use std::old_io::{File, Open, Write, IoError};
 //! fn write_message() -> Result<(), IoError> {
 //!     let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
 //!     try!(file.write_line("important message"));
@@ -167,7 +167,7 @@
 //! It replaces this:
 //!
 //! ```
-//! use std::io::{File, Open, Write, IoError};
+//! use std::old_io::{File, Open, Write, IoError};
 //!
 //! struct Info {
 //!     name: String,
@@ -191,7 +191,7 @@
 //! With this:
 //!
 //! ```
-//! use std::io::{File, Open, Write, IoError};
+//! use std::old_io::{File, Open, Write, IoError};
 //!
 //! struct Info {
 //!     name: String,
@@ -445,7 +445,7 @@ impl<T, E> Result<T, E> {
     /// ignoring I/O and parse errors:
     ///
     /// ```
-    /// use std::io::IoResult;
+    /// use std::old_io::IoResult;
     ///
     /// let mut buffer = &mut b"1\n2\n3\n4\n";
     ///