Rollup merge of rust-lang#23664 - bluss:std-docs, r=steveklabnik

Main motivation was to update docs for the removal or "demotion" of certain extension traits. The update to the slice docs was larger, since the text was largely outdated.

src/libcollections/slice.rs

@@ -13,25 +13,23 @@
 //! The `slice` module contains useful code to help work with slice values.
 //! Slices are a view into a block of memory represented as a pointer and a length.
 //!
-//! ```rust
-//! # #![feature(core)]
+//! ```
 //! // slicing a Vec
-//! let vec = vec!(1, 2, 3);
-//! let int_slice = vec.as_slice();
+//! let vec = vec![1, 2, 3];
+//! let int_slice = &vec[..];
 //! // coercing an array to a slice
 //! let str_slice: &[&str] = &["one", "two", "three"];
 //! ```
 //!
 //! Slices are either mutable or shared. The shared slice type is `&[T]`,
-//! while the mutable slice type is `&mut[T]`. For example, you can mutate the
-//! block of memory that a mutable slice points to:
+//! while the mutable slice type is `&mut [T]`, where `T` represents the element
+//! type. For example, you can mutate the block of memory that a mutable slice
+//! points to:
 //!
-//! ```rust
-//! let x: &mut[i32] = &mut [1, 2, 3];
+//! ```
+//! let x = &mut [1, 2, 3];
 //! x[1] = 7;
-//! assert_eq!(x[0], 1);
-//! assert_eq!(x[1], 7);
-//! assert_eq!(x[2], 3);
+//! assert_eq!(x, &[1, 7, 3]);
 //! ```
 //!
 //! Here are some of the things this module contains:
@@ -41,49 +39,43 @@
 //! There are several structs that are useful for slices, such as `Iter`, which
 //! represents iteration over a slice.
 //!
-//! ## Traits
-//!
-//! A number of traits add methods that allow you to accomplish tasks
-//! with slices, the most important being `SliceExt`. Other traits
-//! apply only to slices of elements satisfying certain bounds (like
-//! `Ord`).
-//!
-//! An example is the `slice` method which enables slicing syntax `[a..b]` that
-//! returns an immutable "view" into a `Vec` or another slice from the index
-//! interval `[a, b)`:
-//!
-//! ```rust
-//! fn main() {
-//!     let numbers = [0, 1, 2];
-//!     let last_numbers = &numbers[1..3];
-//!     // last_numbers is now &[1, 2]
-//! }
-//! ```
-//!
-//! ## Implementations of other traits
+//! ## Trait Implementations
 //!
 //! There are several implementations of common traits for slices. Some examples
 //! include:
 //!
 //! * `Clone`
-//! * `Eq`, `Ord` - for immutable slices whose element type are `Eq` or `Ord`.
+//! * `Eq`, `Ord` - for slices whose element type are `Eq` or `Ord`.
 //! * `Hash` - for slices whose element type is `Hash`
 //!
 //! ## Iteration
 //!
-//! The method `iter()` returns an iteration value for a slice. The iterator
-//! yields references to the slice's elements, so if the element
-//! type of the slice is `isize`, the element type of the iterator is `&isize`.
+//! The slices implement `IntoIterator`. The iterators of yield references
+//! to the slice elements.
 //!
-//! ```rust
-//! let numbers = [0, 1, 2];
-//! for &x in numbers.iter() {
-//!     println!("{} is a number!", x);
+//! ```
+//! let numbers = &[0, 1, 2];
+//! for n in numbers {
+//!     println!("{} is a number!", n);
 //! }
 //! ```
 //!
-//! * `.iter_mut()` returns an iterator that allows modifying each value.
-//! * Further iterators exist that split, chunk or permute the slice.
+//! The mutable slice yields mutable references to the elements:
+//!
+//! ```
+//! let mut scores = [7, 8, 9];
+//! for score in &mut scores[..] {
+//!     *score += 1;
+//! }
+//! ```
+//!
+//! This iterator yields mutable references to the slice's elements, so while the element
+//! type of the slice is `i32`, the element type of the iterator is `&mut i32`.
+//!
+//! * `.iter()` and `.iter_mut()` are the explicit methods to return the default
+//!   iterators.
+//! * Further methods that return iterators are `.split()`, `.splitn()`,
+//!   `.chunks()`, `.windows()` and more.
 
 #![doc(primitive = "slice")]
 #![stable(feature = "rust1", since = "1.0.0")]

src/libcollections/str.rs

@@ -19,7 +19,7 @@
 //! are owned elsewhere.
 //!
 //! Basic operations are implemented directly by the compiler, but more advanced
-//! operations are defined on the [`StrExt`](trait.StrExt.html) trait.
+//! operations are defined as methods on the `str` type.
 //!
 //! # Examples
 //!

src/libcore/str/mod.rs

@@ -165,8 +165,7 @@ impl FromStr for bool {
     /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
     /// ```
     ///
-    /// Note, in many cases, the StrExt::parse() which is based on
-    /// this FromStr::from_str() is more proper.
+    /// Note, in many cases, the `.parse()` method on `str` is more proper.
     ///
     /// ```
     /// assert_eq!("true".parse(), Ok(true));
@@ -531,7 +530,7 @@ impl<'a> DoubleEndedIterator for CharIndices<'a> {
 /// External iterator for a string's bytes.
 /// Use with the `std::iter` module.
 ///
-/// Created with `StrExt::bytes`
+/// Created with `str::bytes`
 #[stable(feature = "rust1", since = "1.0.0")]
 #[derive(Clone)]
 pub struct Bytes<'a>(Map<slice::Iter<'a, u8>, BytesDeref>);
@@ -1489,27 +1488,27 @@ impl<'a, S: ?Sized> Str for &'a S where S: Str {
     fn as_slice(&self) -> &str { Str::as_slice(*self) }
 }
 
-/// Return type of `StrExt::split`
+/// Return type of `str::split`
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Split<'a, P: Pattern<'a>>(CharSplits<'a, P>);
 delegate_iter!{pattern &'a str : Split<'a, P>}
 
-/// Return type of `StrExt::split_terminator`
+/// Return type of `str::split_terminator`
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct SplitTerminator<'a, P: Pattern<'a>>(CharSplits<'a, P>);
 delegate_iter!{pattern &'a str : SplitTerminator<'a, P>}
 
-/// Return type of `StrExt::splitn`
+/// Return type of `str::splitn`
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct SplitN<'a, P: Pattern<'a>>(CharSplitsN<'a, P>);
 delegate_iter!{pattern forward &'a str : SplitN<'a, P>}
 
-/// Return type of `StrExt::rsplit`
+/// Return type of `str::rsplit`
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RSplit<'a, P: Pattern<'a>>(RCharSplits<'a, P>);
 delegate_iter!{pattern reverse &'a str : RSplit<'a, P>}
 
-/// Return type of `StrExt::rsplitn`
+/// Return type of `str::rsplitn`
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct RSplitN<'a, P: Pattern<'a>>(RCharSplitsN<'a, P>);
 delegate_iter!{pattern reverse &'a str : RSplitN<'a, P>}

src/libstd/io/mod.rs

@@ -631,14 +631,14 @@ pub trait BufRead: Read {
 
 /// A `Write` adaptor which will write data to multiple locations.
 ///
-/// For more information, see `WriteExt::broadcast`.
-#[unstable(feature = "io", reason = "awaiting stability of WriteExt::broadcast")]
+/// For more information, see `Write::broadcast`.
+#[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
 pub struct Broadcast<T, U> {
     first: T,
     second: U,
 }
 
-#[unstable(feature = "io", reason = "awaiting stability of WriteExt::broadcast")]
+#[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
 impl<T: Write, U: Write> Write for Broadcast<T, U> {
     fn write(&mut self, data: &[u8]) -> Result<usize> {
         let n = try!(self.first.write(data));
@@ -654,7 +654,7 @@ impl<T: Write, U: Write> Write for Broadcast<T, U> {
 
 /// Adaptor to chain together two instances of `Read`.
 ///
-/// For more information, see `ReadExt::chain`.
+/// For more information, see `Read::chain`.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Chain<T, U> {
     first: T,
@@ -677,7 +677,7 @@ impl<T: Read, U: Read> Read for Chain<T, U> {
 
 /// Reader adaptor which limits the bytes read from an underlying reader.
 ///
-/// For more information, see `ReadExt::take`.
+/// For more information, see `Read::take`.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Take<T> {
     inner: T,
@@ -730,14 +730,14 @@ impl<T: BufRead> BufRead for Take<T> {
 
 /// An adaptor which will emit all read data to a specified writer as well.
 ///
-/// For more information see `ReadExt::tee`
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::tee")]
+/// For more information see `Read::tee`
+#[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
 pub struct Tee<R, W> {
     reader: R,
     writer: W,
 }
 
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::tee")]
+#[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
 impl<R: Read, W: Write> Read for Tee<R, W> {
     fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
         let n = try!(self.reader.read(buf));
@@ -749,7 +749,7 @@ impl<R: Read, W: Write> Read for Tee<R, W> {
 
 /// A bridge from implementations of `Read` to an `Iterator` of `u8`.
 ///
-/// See `ReadExt::bytes` for more information.
+/// See `Read::bytes` for more information.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Bytes<R> {
     inner: R,
@@ -771,16 +771,16 @@ impl<R: Read> Iterator for Bytes<R> {
 
 /// A bridge from implementations of `Read` to an `Iterator` of `char`.
 ///
-/// See `ReadExt::chars` for more information.
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
+/// See `Read::chars` for more information.
+#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
 pub struct Chars<R> {
     inner: R,
 }
 
 /// An enumeration of possible errors that can be generated from the `Chars`
 /// adapter.
 #[derive(PartialEq, Clone, Debug)]
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
+#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
 pub enum CharsError {
     /// Variant representing that the underlying stream was read successfully
     /// but it did not contain valid utf8 data.
@@ -790,7 +790,7 @@ pub enum CharsError {
     Other(Error),
 }
 
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
+#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
 impl<R: Read> Iterator for Chars<R> {
     type Item = result::Result<char, CharsError>;
 
@@ -822,7 +822,7 @@ impl<R: Read> Iterator for Chars<R> {
     }
 }
 
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
+#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
 impl std_error::Error for CharsError {
     fn description(&self) -> &str {
         match *self {
@@ -838,7 +838,7 @@ impl std_error::Error for CharsError {
     }
 }
 
-#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
+#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
 impl fmt::Display for CharsError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match *self {

src/libstd/io/prelude.rs

@@ -18,7 +18,7 @@
 //! ```
 //!
 //! This module contains reexports of many core I/O traits such as `Read`,
-//! `Write`, `ReadExt`, and `WriteExt`. Structures and functions are not
+//! `Write` and `BufRead`. Structures and functions are not
 //! contained in this module.
 
 #![stable(feature = "rust1", since = "1.0.0")]