From 9ad133b4a14191a89687b45fa0deec3c6041a80d Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Mon, 6 Apr 2015 15:58:23 -0700
Subject: rustdoc: Add a primitive page for raw pointers

Closes #15318
---
 src/libcore/ptr.rs | 1 +
 1 file changed, 1 insertion(+)

(limited to 'src/libcore')

diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index ff51e25fcbf..10cd793a3d2 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -89,6 +89,7 @@
 //! of unsafe pointers in Rust.
 
 #![stable(feature = "rust1", since = "1.0.0")]
+#![doc(primitive = "pointer")]
 
 use mem;
 use clone::Clone;
-- 
cgit 1.4.1-3-g733a5


From ba402312fed8134a9919bbb79bcd9978b92e4dee Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Mon, 6 Apr 2015 18:52:18 -0700
Subject: std: Deny most warnings in doctests

Allow a few specific ones but otherwise this helps ensure that our examples are
squeaky clean!

Closes #18199
---
 src/libcore/macros.rs              |   1 -
 src/libstd/collections/hash/set.rs |   8 -
 src/libstd/collections/mod.rs      | 335 ++++++++++++++++++++-----------------
 src/libstd/fs.rs                   |  25 +--
 src/libstd/io/prelude.rs           |   1 +
 src/libstd/lib.rs                  |   3 +-
 src/libstd/net/addr.rs             |   3 +-
 src/libstd/net/tcp.rs              |   2 -
 src/libstd/net/udp.rs              |   1 -
 src/libstd/num/f32.rs              |   7 +-
 src/libstd/num/mod.rs              |  19 +--
 src/libstd/old_io/mod.rs           |   2 +-
 src/libstd/old_io/net/ip.rs        |   2 +-
 src/libstd/old_io/net/pipe.rs      |   2 +-
 src/libstd/old_io/process.rs       |   2 +-
 src/libstd/old_path/mod.rs         |  16 +-
 src/libstd/process.rs              |   7 +-
 src/libstd/thread/mod.rs           |   1 +
 18 files changed, 212 insertions(+), 225 deletions(-)

(limited to 'src/libcore')

diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index c21898d088d..ece419af951 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -229,7 +229,6 @@ macro_rules! writeln {
 /// Iterators:
 ///
 /// ```
-/// # #![feature(core)]
 /// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3
 ///     for i in 0.. {
 ///         if 3*i < i { panic!("u32 overflow"); }
diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs
index 5fbc21797ab..f897d565321 100644
--- a/src/libstd/collections/hash/set.rs
+++ b/src/libstd/collections/hash/set.rs
@@ -304,7 +304,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     /// let a: HashSet<_> = [1, 2, 3].iter().cloned().collect();
     /// let b: HashSet<_> = [4, 2, 3, 4].iter().cloned().collect();
@@ -335,7 +334,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     /// let a: HashSet<_> = [1, 2, 3].iter().cloned().collect();
     /// let b: HashSet<_> = [4, 2, 3, 4].iter().cloned().collect();
@@ -362,7 +360,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     /// let a: HashSet<_> = [1, 2, 3].iter().cloned().collect();
     /// let b: HashSet<_> = [4, 2, 3, 4].iter().cloned().collect();
@@ -388,7 +385,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     /// let a: HashSet<_> = [1, 2, 3].iter().cloned().collect();
     /// let b: HashSet<_> = [4, 2, 3, 4].iter().cloned().collect();
@@ -471,7 +467,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     ///
     /// let set: HashSet<_> = [1, 2, 3].iter().cloned().collect();
@@ -491,7 +486,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     ///
     /// let a: HashSet<_> = [1, 2, 3].iter().cloned().collect();
@@ -513,7 +507,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     ///
     /// let sup: HashSet<_> = [1, 2, 3].iter().cloned().collect();
@@ -535,7 +528,6 @@ impl<T, S> HashSet<T, S>
     /// # Examples
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::collections::HashSet;
     ///
     /// let sub: HashSet<_> = [1, 2].iter().cloned().collect();
diff --git a/src/libstd/collections/mod.rs b/src/libstd/collections/mod.rs
index 0ac97b71298..48b95ce6439 100644
--- a/src/libstd/collections/mod.rs
+++ b/src/libstd/collections/mod.rs
@@ -10,16 +10,18 @@
 
 //! Collection types.
 //!
-//! Rust's standard collection library provides efficient implementations of the most common
-//! general purpose programming data structures. By using the standard implementations,
-//! it should be possible for two libraries to communicate without significant data conversion.
-//!
-//! To get this out of the way: you should probably just use `Vec` or `HashMap`. These two
-//! collections cover most use cases for generic data storage and processing. They are
-//! exceptionally good at doing what they do. All the other collections in the standard
-//! library have specific use cases where they are the optimal choice, but these cases are
-//! borderline *niche* in comparison. Even when `Vec` and `HashMap` are technically suboptimal,
-//! they're probably a good enough choice to get started.
+//! Rust's standard collection library provides efficient implementations of the
+//! most common general purpose programming data structures. By using the
+//! standard implementations, it should be possible for two libraries to
+//! communicate without significant data conversion.
+//!
+//! To get this out of the way: you should probably just use `Vec` or `HashMap`.
+//! These two collections cover most use cases for generic data storage and
+//! processing. They are exceptionally good at doing what they do. All the other
+//! collections in the standard library have specific use cases where they are
+//! the optimal choice, but these cases are borderline *niche* in comparison.
+//! Even when `Vec` and `HashMap` are technically suboptimal, they're probably a
+//! good enough choice to get started.
 //!
 //! Rust's collections can be grouped into four major categories:
 //!
@@ -30,28 +32,31 @@
 //!
 //! # When Should You Use Which Collection?
 //!
-//! These are fairly high-level and quick break-downs of when each collection should be
-//! considered. Detailed discussions of strengths and weaknesses of individual collections
-//! can be found on their own documentation pages.
+//! These are fairly high-level and quick break-downs of when each collection
+//! should be considered. Detailed discussions of strengths and weaknesses of
+//! individual collections can be found on their own documentation pages.
 //!
 //! ### Use a `Vec` when:
-//! * You want to collect items up to be processed or sent elsewhere later, and don't care about
-//! any properties of the actual values being stored.
-//! * You want a sequence of elements in a particular order, and will only be appending to
-//! (or near) the end.
+//! * You want to collect items up to be processed or sent elsewhere later, and
+//!   don't care about any properties of the actual values being stored.
+//! * You want a sequence of elements in a particular order, and will only be
+//!   appending to (or near) the end.
 //! * You want a stack.
 //! * You want a resizable array.
 //! * You want a heap-allocated array.
 //!
 //! ### Use a `VecDeque` when:
-//! * You want a `Vec` that supports efficient insertion at both ends of the sequence.
+//! * You want a `Vec` that supports efficient insertion at both ends of the
+//!   sequence.
 //! * You want a queue.
 //! * You want a double-ended queue (deque).
 //!
 //! ### Use a `LinkedList` when:
-//! * You want a `Vec` or `VecDeque` of unknown size, and can't tolerate amortization.
+//! * You want a `Vec` or `VecDeque` of unknown size, and can't tolerate
+//!   amortization.
 //! * You want to efficiently split and append lists.
-//! * You are *absolutely* certain you *really*, *truly*, want a doubly linked list.
+//! * You are *absolutely* certain you *really*, *truly*, want a doubly linked
+//!   list.
 //!
 //! ### Use a `HashMap` when:
 //! * You want to associate arbitrary keys with an arbitrary value.
@@ -60,7 +65,8 @@
 //!
 //! ### Use a `BTreeMap` when:
 //! * You're interested in what the smallest or largest key-value pair is.
-//! * You want to find the largest or smallest key that is smaller or larger than something
+//! * You want to find the largest or smallest key that is smaller or larger
+//!   than something
 //! * You want to be able to get all of the entries in order on-demand.
 //! * You want a sorted map.
 //!
@@ -81,29 +87,34 @@
 //! * You want a `BitVec`, but want `Set` properties
 //!
 //! ### Use a `BinaryHeap` when:
-//! * You want to store a bunch of elements, but only ever want to process the "biggest"
-//! or "most important" one at any given time.
+//!
+//! * You want to store a bunch of elements, but only ever want to process the
+//!   "biggest" or "most important" one at any given time.
 //! * You want a priority queue.
 //!
 //! # Performance
 //!
-//! Choosing the right collection for the job requires an understanding of what each collection
-//! is good at. Here we briefly summarize the performance of different collections for certain
-//! important operations. For further details, see each type's documentation, and note that the
-//! names of actual methods may differ from the tables below on certain collections.
+//! Choosing the right collection for the job requires an understanding of what
+//! each collection is good at. Here we briefly summarize the performance of
+//! different collections for certain important operations. For further details,
+//! see each type's documentation, and note that the names of actual methods may
+//! differ from the tables below on certain collections.
 //!
-//! Throughout the documentation, we will follow a few conventions. For all operations,
-//! the collection's size is denoted by n. If another collection is involved in the operation, it
-//! contains m elements. Operations which have an *amortized* cost are suffixed with a `*`.
-//! Operations with an *expected* cost are suffixed with a `~`.
+//! Throughout the documentation, we will follow a few conventions. For all
+//! operations, the collection's size is denoted by n. If another collection is
+//! involved in the operation, it contains m elements. Operations which have an
+//! *amortized* cost are suffixed with a `*`.  Operations with an *expected*
+//! cost are suffixed with a `~`.
 //!
-//! All amortized costs are for the potential need to resize when capacity is exhausted.
-//! If a resize occurs it will take O(n) time. Our collections never automatically shrink,
-//! so removal operations aren't amortized. Over a sufficiently large series of
-//! operations, the average cost per operation will deterministically equal the given cost.
+//! All amortized costs are for the potential need to resize when capacity is
+//! exhausted.  If a resize occurs it will take O(n) time. Our collections never
+//! automatically shrink, so removal operations aren't amortized. Over a
+//! sufficiently large series of operations, the average cost per operation will
+//! deterministically equal the given cost.
 //!
-//! Only HashMap has expected costs, due to the probabilistic nature of hashing. It is
-//! theoretically possible, though very unlikely, for HashMap to experience worse performance.
+//! Only HashMap has expected costs, due to the probabilistic nature of hashing.
+//! It is theoretically possible, though very unlikely, for HashMap to
+//! experience worse performance.
 //!
 //! ## Sequences
 //!
@@ -120,7 +131,8 @@
 //!
 //! ## Maps
 //!
-//! For Sets, all operations have the cost of the equivalent Map operation. For BitSet,
+//! For Sets, all operations have the cost of the equivalent Map operation. For
+//! BitSet,
 //! refer to VecMap.
 //!
 //! |          | get       | insert   | remove   | predecessor |
@@ -129,85 +141,95 @@
 //! | BTreeMap | O(log n)  | O(log n) | O(log n) | O(log n)    |
 //! | VecMap   | O(1)      | O(1)?    | O(1)     | O(n)        |
 //!
-//! Note that VecMap is *incredibly* inefficient in terms of space. The O(1) insertion time
-//! assumes space for the element is already allocated. Otherwise, a large key may require a
-//! massive reallocation, with no direct relation to the number of elements in the collection.
-//! VecMap should only be seriously considered for small keys.
+//! Note that VecMap is *incredibly* inefficient in terms of space. The O(1)
+//! insertion time assumes space for the element is already allocated.
+//! Otherwise, a large key may require a massive reallocation, with no direct
+//! relation to the number of elements in the collection.  VecMap should only be
+//! seriously considered for small keys.
 //!
 //! Note also that BTreeMap's precise preformance depends on the value of B.
 //!
 //! # Correct and Efficient Usage of Collections
 //!
-//! Of course, knowing which collection is the right one for the job doesn't instantly
-//! permit you to use it correctly. Here are some quick tips for efficient and correct
-//! usage of the standard collections in general. If you're interested in how to use a
-//! specific collection in particular, consult its documentation for detailed discussion
-//! and code examples.
+//! Of course, knowing which collection is the right one for the job doesn't
+//! instantly permit you to use it correctly. Here are some quick tips for
+//! efficient and correct usage of the standard collections in general. If
+//! you're interested in how to use a specific collection in particular, consult
+//! its documentation for detailed discussion and code examples.
 //!
 //! ## Capacity Management
 //!
-//! Many collections provide several constructors and methods that refer to "capacity".
-//! These collections are generally built on top of an array. Optimally, this array would be
-//! exactly the right size to fit only the elements stored in the collection, but for the
-//! collection to do this would be very inefficient. If the backing array was exactly the
-//! right size at all times, then every time an element is inserted, the collection would
-//! have to grow the array to fit it. Due to the way memory is allocated and managed on most
-//! computers, this would almost surely require allocating an entirely new array and
-//! copying every single element from the old one into the new one. Hopefully you can
-//! see that this wouldn't be very efficient to do on every operation.
-//!
-//! Most collections therefore use an *amortized* allocation strategy. They generally let
-//! themselves have a fair amount of unoccupied space so that they only have to grow
-//! on occasion. When they do grow, they allocate a substantially larger array to move
-//! the elements into so that it will take a while for another grow to be required. While
-//! this strategy is great in general, it would be even better if the collection *never*
-//! had to resize its backing array. Unfortunately, the collection itself doesn't have
-//! enough information to do this itself. Therefore, it is up to us programmers to give it
-//! hints.
-//!
-//! Any `with_capacity` constructor will instruct the collection to allocate enough space
-//! for the specified number of elements. Ideally this will be for exactly that many
-//! elements, but some implementation details may prevent this. `Vec` and `VecDeque` can
-//! be relied on to allocate exactly the requested amount, though. Use `with_capacity`
-//! when you know exactly how many elements will be inserted, or at least have a
-//! reasonable upper-bound on that number.
-//!
-//! When anticipating a large influx of elements, the `reserve` family of methods can
-//! be used to hint to the collection how much room it should make for the coming items.
-//! As with `with_capacity`, the precise behavior of these methods will be specific to
-//! the collection of interest.
-//!
-//! For optimal performance, collections will generally avoid shrinking themselves.
-//! If you believe that a collection will not soon contain any more elements, or
-//! just really need the memory, the `shrink_to_fit` method prompts the collection
-//! to shrink the backing array to the minimum size capable of holding its elements.
-//!
-//! Finally, if ever you're interested in what the actual capacity of the collection is,
-//! most collections provide a `capacity` method to query this information on demand.
-//! This can be useful for debugging purposes, or for use with the `reserve` methods.
+//! Many collections provide several constructors and methods that refer to
+//! "capacity".  These collections are generally built on top of an array.
+//! Optimally, this array would be exactly the right size to fit only the
+//! elements stored in the collection, but for the collection to do this would
+//! be very inefficient. If the backing array was exactly the right size at all
+//! times, then every time an element is inserted, the collection would have to
+//! grow the array to fit it. Due to the way memory is allocated and managed on
+//! most computers, this would almost surely require allocating an entirely new
+//! array and copying every single element from the old one into the new one.
+//! Hopefully you can see that this wouldn't be very efficient to do on every
+//! operation.
+//!
+//! Most collections therefore use an *amortized* allocation strategy. They
+//! generally let themselves have a fair amount of unoccupied space so that they
+//! only have to grow on occasion. When they do grow, they allocate a
+//! substantially larger array to move the elements into so that it will take a
+//! while for another grow to be required. While this strategy is great in
+//! general, it would be even better if the collection *never* had to resize its
+//! backing array. Unfortunately, the collection itself doesn't have enough
+//! information to do this itself. Therefore, it is up to us programmers to give
+//! it hints.
+//!
+//! Any `with_capacity` constructor will instruct the collection to allocate
+//! enough space for the specified number of elements. Ideally this will be for
+//! exactly that many elements, but some implementation details may prevent
+//! this. `Vec` and `VecDeque` can be relied on to allocate exactly the
+//! requested amount, though. Use `with_capacity` when you know exactly how many
+//! elements will be inserted, or at least have a reasonable upper-bound on that
+//! number.
+//!
+//! When anticipating a large influx of elements, the `reserve` family of
+//! methods can be used to hint to the collection how much room it should make
+//! for the coming items.  As with `with_capacity`, the precise behavior of
+//! these methods will be specific to the collection of interest.
+//!
+//! For optimal performance, collections will generally avoid shrinking
+//! themselves.  If you believe that a collection will not soon contain any more
+//! elements, or just really need the memory, the `shrink_to_fit` method prompts
+//! the collection to shrink the backing array to the minimum size capable of
+//! holding its elements.
+//!
+//! Finally, if ever you're interested in what the actual capacity of the
+//! collection is, most collections provide a `capacity` method to query this
+//! information on demand.  This can be useful for debugging purposes, or for
+//! use with the `reserve` methods.
 //!
 //! ## Iterators
 //!
-//! Iterators are a powerful and robust mechanism used throughout Rust's standard
-//! libraries. Iterators provide a sequence of values in a generic, safe, efficient
-//! and convenient way. The contents of an iterator are usually *lazily* evaluated,
-//! so that only the values that are actually needed are ever actually produced, and
-//! no allocation need be done to temporarily store them. Iterators are primarily
-//! consumed using a `for` loop, although many functions also take iterators where
-//! a collection or sequence of values is desired.
-//!
-//! All of the standard collections provide several iterators for performing bulk
-//! manipulation of their contents. The three primary iterators almost every collection
-//! should provide are `iter`, `iter_mut`, and `into_iter`. Some of these are not
-//! provided on collections where it would be unsound or unreasonable to provide them.
+//! Iterators are a powerful and robust mechanism used throughout Rust's
+//! standard libraries. Iterators provide a sequence of values in a generic,
+//! safe, efficient and convenient way. The contents of an iterator are usually
+//! *lazily* evaluated, so that only the values that are actually needed are
+//! ever actually produced, and no allocation need be done to temporarily store
+//! them. Iterators are primarily consumed using a `for` loop, although many
+//! functions also take iterators where a collection or sequence of values is
+//! desired.
+//!
+//! All of the standard collections provide several iterators for performing
+//! bulk manipulation of their contents. The three primary iterators almost
+//! every collection should provide are `iter`, `iter_mut`, and `into_iter`.
+//! Some of these are not provided on collections where it would be unsound or
+//! unreasonable to provide them.
 //!
 //! `iter` provides an iterator of immutable references to all the contents of a
-//! collection in the most "natural" order. For sequence collections like `Vec`, this
-//! means the items will be yielded in increasing order of index starting at 0. For ordered
-//! collections like `BTreeMap`, this means that the items will be yielded in sorted order.
-//! For unordered collections like `HashMap`, the items will be yielded in whatever order
-//! the internal representation made most convenient. This is great for reading through
-//! all the contents of the collection.
+//! collection in the most "natural" order. For sequence collections like `Vec`,
+//! this means the items will be yielded in increasing order of index starting
+//! at 0. For ordered collections like `BTreeMap`, this means that the items
+//! will be yielded in sorted order.  For unordered collections like `HashMap`,
+//! the items will be yielded in whatever order the internal representation made
+//! most convenient. This is great for reading through all the contents of the
+//! collection.
 //!
 //! ```
 //! let vec = vec![1, 2, 3, 4];
@@ -216,8 +238,8 @@
 //! }
 //! ```
 //!
-//! `iter_mut` provides an iterator of *mutable* references in the same order as `iter`.
-//! This is great for mutating all the contents of the collection.
+//! `iter_mut` provides an iterator of *mutable* references in the same order as
+//! `iter`.  This is great for mutating all the contents of the collection.
 //!
 //! ```
 //! let mut vec = vec![1, 2, 3, 4];
@@ -226,13 +248,14 @@
 //! }
 //! ```
 //!
-//! `into_iter` transforms the actual collection into an iterator over its contents
-//! by-value. This is great when the collection itself is no longer needed, and the
-//! values are needed elsewhere. Using `extend` with `into_iter` is the main way that
-//! contents of one collection are moved into another. Calling `collect` on an iterator
-//! itself is also a great way to convert one collection into another. Both of these
-//! methods should internally use the capacity management tools discussed in the
-//! previous section to do this as efficiently as possible.
+//! `into_iter` transforms the actual collection into an iterator over its
+//! contents by-value. This is great when the collection itself is no longer
+//! needed, and the values are needed elsewhere. Using `extend` with `into_iter`
+//! is the main way that contents of one collection are moved into another.
+//! Calling `collect` on an iterator itself is also a great way to convert one
+//! collection into another. Both of these methods should internally use the
+//! capacity management tools discussed in the previous section to do this as
+//! efficiently as possible.
 //!
 //! ```
 //! let mut vec1 = vec![1, 2, 3, 4];
@@ -247,11 +270,12 @@
 //! let buf: VecDeque<_> = vec.into_iter().collect();
 //! ```
 //!
-//! Iterators also provide a series of *adapter* methods for performing common tasks to
-//! sequences. Among the adapters are functional favorites like `map`, `fold`, `skip`,
-//! and `take`. Of particular interest to collections is the `rev` adapter, that
-//! reverses any iterator that supports this operation. Most collections provide reversible
-//! iterators as the way to iterate over them in reverse order.
+//! Iterators also provide a series of *adapter* methods for performing common
+//! tasks to sequences. Among the adapters are functional favorites like `map`,
+//! `fold`, `skip`, and `take`. Of particular interest to collections is the
+//! `rev` adapter, that reverses any iterator that supports this operation. Most
+//! collections provide reversible iterators as the way to iterate over them in
+//! reverse order.
 //!
 //! ```
 //! let vec = vec![1, 2, 3, 4];
@@ -260,48 +284,50 @@
 //! }
 //! ```
 //!
-//! Several other collection methods also return iterators to yield a sequence of results
-//! but avoid allocating an entire collection to store the result in. This provides maximum
-//! flexibility as `collect` or `extend` can be called to "pipe" the sequence into any
-//! collection if desired. Otherwise, the sequence can be looped over with a `for` loop. The
-//! iterator can also be discarded after partial use, preventing the computation of the unused
-//! items.
+//! Several other collection methods also return iterators to yield a sequence
+//! of results but avoid allocating an entire collection to store the result in.
+//! This provides maximum flexibility as `collect` or `extend` can be called to
+//! "pipe" the sequence into any collection if desired. Otherwise, the sequence
+//! can be looped over with a `for` loop. The iterator can also be discarded
+//! after partial use, preventing the computation of the unused items.
 //!
 //! ## Entries
 //!
-//! The `entry` API is intended to provide an efficient mechanism for manipulating
-//! the contents of a map conditionally on the presence of a key or not. The primary
-//! motivating use case for this is to provide efficient accumulator maps. For instance,
-//! if one wishes to maintain a count of the number of times each key has been seen,
-//! they will have to perform some conditional logic on whether this is the first time
-//! the key has been seen or not. Normally, this would require a `find` followed by an
-//! `insert`, effectively duplicating the search effort on each insertion.
-//!
-//! When a user calls `map.entry(&key)`, the map will search for the key and then yield
-//! a variant of the `Entry` enum.
-//!
-//! If a `Vacant(entry)` is yielded, then the key *was not* found. In this case the
-//! only valid operation is to `insert` a value into the entry. When this is done,
-//! the vacant entry is consumed and converted into a mutable reference to the
-//! the value that was inserted. This allows for further manipulation of the value
-//! beyond the lifetime of the search itself. This is useful if complex logic needs to
-//! be performed on the value regardless of whether the value was just inserted.
-//!
-//! If an `Occupied(entry)` is yielded, then the key *was* found. In this case, the user
-//! has several options: they can `get`, `insert`, or `remove` the value of the occupied
-//! entry. Additionally, they can convert the occupied entry into a mutable reference
-//! to its value, providing symmetry to the vacant `insert` case.
+//! The `entry` API is intended to provide an efficient mechanism for
+//! manipulating the contents of a map conditionally on the presence of a key or
+//! not. The primary motivating use case for this is to provide efficient
+//! accumulator maps. For instance, if one wishes to maintain a count of the
+//! number of times each key has been seen, they will have to perform some
+//! conditional logic on whether this is the first time the key has been seen or
+//! not. Normally, this would require a `find` followed by an `insert`,
+//! effectively duplicating the search effort on each insertion.
+//!
+//! When a user calls `map.entry(&key)`, the map will search for the key and
+//! then yield a variant of the `Entry` enum.
+//!
+//! If a `Vacant(entry)` is yielded, then the key *was not* found. In this case
+//! the only valid operation is to `insert` a value into the entry. When this is
+//! done, the vacant entry is consumed and converted into a mutable reference to
+//! the the value that was inserted. This allows for further manipulation of the
+//! value beyond the lifetime of the search itself. This is useful if complex
+//! logic needs to be performed on the value regardless of whether the value was
+//! just inserted.
+//!
+//! If an `Occupied(entry)` is yielded, then the key *was* found. In this case,
+//! the user has several options: they can `get`, `insert`, or `remove` the
+//! value of the occupied entry. Additionally, they can convert the occupied
+//! entry into a mutable reference to its value, providing symmetry to the
+//! vacant `insert` case.
 //!
 //! ### Examples
 //!
-//! Here are the two primary ways in which `entry` is used. First, a simple example
-//! where the logic performed on the values is trivial.
+//! Here are the two primary ways in which `entry` is used. First, a simple
+//! example where the logic performed on the values is trivial.
 //!
 //! #### Counting the number of times each character in a string occurs
 //!
 //! ```
-//! # #![feature(collections)]
-//! use std::collections::btree_map::{BTreeMap, Entry};
+//! use std::collections::btree_map::BTreeMap;
 //!
 //! let mut count = BTreeMap::new();
 //! let message = "she sells sea shells by the sea shore";
@@ -318,15 +344,14 @@
 //! }
 //! ```
 //!
-//! When the logic to be performed on the value is more complex, we may simply use
-//! the `entry` API to ensure that the value is initialized, and perform the logic
-//! afterwards.
+//! When the logic to be performed on the value is more complex, we may simply
+//! use the `entry` API to ensure that the value is initialized, and perform the
+//! logic afterwards.
 //!
 //! #### Tracking the inebriation of customers at a bar
 //!
 //! ```
-//! # #![feature(collections)]
-//! use std::collections::btree_map::{BTreeMap, Entry};
+//! use std::collections::btree_map::BTreeMap;
 //!
 //! // A client of the bar. They have an id and a blood alcohol level.
 //! struct Person { id: u32, blood_alcohol: f32 }
diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs
index 4e2dade9a3c..914830d9dcf 100644
--- a/src/libstd/fs.rs
+++ b/src/libstd/fs.rs
@@ -96,14 +96,16 @@ pub struct WalkDir {
 
 /// Options and flags which can be used to configure how a file is opened.
 ///
-/// This builder exposes the ability to configure how a `File` is opened and what operations are
-/// permitted on the open file. The `File::open` and `File::create` methods are aliases for
-/// commonly used options using this builder.
+/// This builder exposes the ability to configure how a `File` is opened and
+/// what operations are permitted on the open file. The `File::open` and
+/// `File::create` methods are aliases for commonly used options using this
+/// builder.
 ///
-/// Generally speaking, when using `OpenOptions`, you'll first call `new()`, then chain calls to
-/// methods to set each option, then call `open()`, passing the path of the file you're trying to
-/// open. This will give you a [`io::Result`][result] with a [`File`][file] inside that you can
-/// further operate on.
+/// Generally speaking, when using `OpenOptions`, you'll first call `new()`,
+/// then chain calls to methods to set each option, then call `open()`, passing
+/// the path of the file you're trying to open. This will give you a
+/// [`io::Result`][result] with a [`File`][file] inside that you can further
+/// operate on.
 ///
 /// [result]: ../io/type.Result.html
 /// [file]: struct.File.html
@@ -113,16 +115,15 @@ pub struct WalkDir {
 /// Opening a file to read:
 ///
 /// ```no_run
-/// use std::fs;
 /// use std::fs::OpenOptions;
 ///
 /// let file = OpenOptions::new().read(true).open("foo.txt");
 /// ```
 ///
-/// Opening a file for both reading and writing, as well as creating it if it doesn't exist:
+/// Opening a file for both reading and writing, as well as creating it if it
+/// doesn't exist:
 ///
 /// ```
-/// use std::fs;
 /// use std::fs::OpenOptions;
 ///
 /// let file = OpenOptions::new()
@@ -771,7 +772,9 @@ pub fn rename<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<()>
 /// ```no_run
 /// use std::fs;
 ///
-/// fs::copy("foo.txt", "bar.txt");
+/// # fn foo() -> std::io::Result<()> {
+/// try!(fs::copy("foo.txt", "bar.txt"));
+/// # Ok(()) }
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> io::Result<u64> {
diff --git a/src/libstd/io/prelude.rs b/src/libstd/io/prelude.rs
index 333ae8f26a0..880770eb414 100644
--- a/src/libstd/io/prelude.rs
+++ b/src/libstd/io/prelude.rs
@@ -14,6 +14,7 @@
 //! by adding a glob import to the top of I/O heavy modules:
 //!
 //! ```
+//! # #![allow(unused_imports)]
 //! use std::io::prelude::*;
 //! ```
 //!
diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs
index df81981c3f4..b329494a052 100644
--- a/src/libstd/lib.rs
+++ b/src/libstd/lib.rs
@@ -103,7 +103,8 @@
        html_favicon_url = "http://www.rust-lang.org/favicon.ico",
        html_root_url = "http://doc.rust-lang.org/nightly/",
        html_playground_url = "http://play.rust-lang.org/")]
-#![doc(test(no_crate_inject))]
+#![doc(test(no_crate_inject, attr(deny(warnings))))]
+#![doc(test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))))]
 
 #![feature(alloc)]
 #![feature(box_syntax)]
diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs
index 886f252fb19..3abf805c7f6 100644
--- a/src/libstd/net/addr.rs
+++ b/src/libstd/net/addr.rs
@@ -281,7 +281,6 @@ impl hash::Hash for SocketAddrV6 {
 /// Some examples:
 ///
 /// ```no_run
-/// # #![feature(net)]
 /// use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};
 ///
 /// fn main() {
@@ -302,7 +301,7 @@ impl hash::Hash for SocketAddrV6 {
 ///     let tcp_l = TcpListener::bind("localhost:12345");
 ///
 ///     let mut udp_s = UdpSocket::bind(("127.0.0.1", port)).unwrap();
-///     udp_s.send_to(&[7], (ip, 23451));
+///     udp_s.send_to(&[7], (ip, 23451)).unwrap();
 /// }
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs
index 04d1013af1f..2da6f7420ac 100644
--- a/src/libstd/net/tcp.rs
+++ b/src/libstd/net/tcp.rs
@@ -27,7 +27,6 @@ use sys_common::{AsInner, FromInner};
 /// # Examples
 ///
 /// ```no_run
-/// # #![feature(net)]
 /// use std::io::prelude::*;
 /// use std::net::TcpStream;
 ///
@@ -47,7 +46,6 @@ pub struct TcpStream(net_imp::TcpStream);
 /// # Examples
 ///
 /// ```no_run
-/// # #![feature(net)]
 /// use std::net::{TcpListener, TcpStream};
 /// use std::thread;
 ///
diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs
index 7b14e4dbea6..bec9c09bc31 100644
--- a/src/libstd/net/udp.rs
+++ b/src/libstd/net/udp.rs
@@ -27,7 +27,6 @@ use sys_common::{AsInner, FromInner};
 /// # Examples
 ///
 /// ```no_run
-/// # #![feature(net)]
 /// use std::net::UdpSocket;
 ///
 /// # fn foo() -> std::io::Result<()> {
diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs
index 0ae4d3c5bd6..6128469c60e 100644
--- a/src/libstd/num/f32.rs
+++ b/src/libstd/num/f32.rs
@@ -422,7 +422,6 @@ impl f32 {
     /// [subnormal][subnormal], or `NaN`.
     ///
     /// ```
-    /// # #![feature(std_misc)]
     /// use std::f32;
     ///
     /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
@@ -856,7 +855,7 @@ impl f32 {
     /// Convert radians to degrees.
     ///
     /// ```
-    /// # #![feature(std_misc, core)]
+    /// # #![feature(std_misc)]
     /// use std::f32::{self, consts};
     ///
     /// let angle = consts::PI;
@@ -987,7 +986,6 @@ impl f32 {
     /// * Else: `self - other`
     ///
     /// ```
-    /// # #![feature(std_misc)]
     /// use std::f32;
     ///
     /// let x = 3.0f32;
@@ -1008,7 +1006,6 @@ impl f32 {
     /// Take the cubic root of a number.
     ///
     /// ```
-    /// # #![feature(std_misc)]
     /// use std::f32;
     ///
     /// let x = 8.0f32;
@@ -1210,8 +1207,6 @@ impl f32 {
     /// number is close to zero.
     ///
     /// ```
-    /// use std::f64;
-    ///
     /// let x = 7.0f64;
     ///
     /// // e^(ln(7)) - 1
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index 2de03e2e72d..ea516e5b20b 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -280,7 +280,6 @@ pub trait Float
     /// [subnormal][subnormal], or `NaN`.
     ///
     /// ```
-    /// # #![feature(std_misc)]
     /// use std::num::Float;
     /// use std::f32;
     ///
@@ -307,7 +306,6 @@ pub trait Float
     /// predicate instead.
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::{Float, FpCategory};
     /// use std::f32;
     ///
@@ -417,7 +415,6 @@ pub trait Float
     /// number is `Float::nan()`.
     ///
     /// ```
-    /// # #![feature(std_misc)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -441,7 +438,6 @@ pub trait Float
     /// - `Float::nan()` if the number is `Float::nan()`
     ///
     /// ```
-    /// # #![feature(std_misc)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -686,7 +682,6 @@ pub trait Float
     /// Convert radians to degrees.
     ///
     /// ```
-    /// # #![feature(std_misc, core)]
     /// use std::num::Float;
     /// use std::f64::consts;
     ///
@@ -701,7 +696,7 @@ pub trait Float
     /// Convert degrees to radians.
     ///
     /// ```
-    /// # #![feature(std_misc, core)]
+    /// # #![feature(std_misc)]
     /// use std::num::Float;
     /// use std::f64::consts;
     ///
@@ -849,7 +844,6 @@ pub trait Float
     /// Computes the sine of a number (in radians).
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -864,7 +858,6 @@ pub trait Float
     /// Computes the cosine of a number (in radians).
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -879,7 +872,6 @@ pub trait Float
     /// Computes the tangent of a number (in radians).
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -895,7 +887,6 @@ pub trait Float
     /// [-1, 1].
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -913,7 +904,6 @@ pub trait Float
     /// [-1, 1].
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -949,7 +939,6 @@ pub trait Float
     /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)`
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -975,7 +964,6 @@ pub trait Float
     /// `(sin(x), cos(x))`.
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -1011,7 +999,6 @@ pub trait Float
     /// the operations were performed separately.
     ///
     /// ```
-    /// # #![feature(std_misc, core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -1028,7 +1015,6 @@ pub trait Float
     /// Hyperbolic sine function.
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -1047,7 +1033,6 @@ pub trait Float
     /// Hyperbolic cosine function.
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -1066,7 +1051,6 @@ pub trait Float
     /// Hyperbolic tangent function.
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
@@ -1113,7 +1097,6 @@ pub trait Float
     /// Inverse hyperbolic tangent function.
     ///
     /// ```
-    /// # #![feature(core)]
     /// use std::num::Float;
     /// use std::f64;
     ///
diff --git a/src/libstd/old_io/mod.rs b/src/libstd/old_io/mod.rs
index 5e93757668c..f62b1a836fd 100644
--- a/src/libstd/old_io/mod.rs
+++ b/src/libstd/old_io/mod.rs
@@ -48,7 +48,7 @@
 //! * Read lines from stdin
 //!
 //!     ```rust
-//!     # #![feature(old_io, old_path)]
+//!     # #![feature(old_io)]
 //!     use std::old_io as io;
 //!     use std::old_io::*;
 //!
diff --git a/src/libstd/old_io/net/ip.rs b/src/libstd/old_io/net/ip.rs
index 099fe657f26..f5310292b91 100644
--- a/src/libstd/old_io/net/ip.rs
+++ b/src/libstd/old_io/net/ip.rs
@@ -414,7 +414,7 @@ pub struct ParseError;
 /// Some examples:
 ///
 /// ```rust,no_run
-/// # #![feature(old_io, core, convert)]
+/// # #![feature(old_io)]
 /// # #![allow(unused_must_use)]
 ///
 /// use std::old_io::{TcpStream, TcpListener};
diff --git a/src/libstd/old_io/net/pipe.rs b/src/libstd/old_io/net/pipe.rs
index 3a071e832af..7b23c3e1d03 100644
--- a/src/libstd/old_io/net/pipe.rs
+++ b/src/libstd/old_io/net/pipe.rs
@@ -191,7 +191,7 @@ impl UnixListener {
     /// let server = Path::new("/path/to/my/socket");
     /// let stream = UnixListener::bind(&server);
     /// for mut client in stream.listen().incoming() {
-    ///     client.write(&[1, 2, 3, 4]);
+    ///     let _ = client.write(&[1, 2, 3, 4]);
     /// }
     /// # }
     /// ```
diff --git a/src/libstd/old_io/process.rs b/src/libstd/old_io/process.rs
index ad2d5b46819..b55d1f4db07 100644
--- a/src/libstd/old_io/process.rs
+++ b/src/libstd/old_io/process.rs
@@ -367,7 +367,7 @@ impl Command {
     /// # Examples
     ///
     /// ```
-    /// # #![feature(old_io, core, convert)]
+    /// # #![feature(old_io)]
     /// use std::old_io::Command;
     ///
     /// let output = match Command::new("cat").arg("foot.txt").output() {
diff --git a/src/libstd/old_path/mod.rs b/src/libstd/old_path/mod.rs
index 9c88533d3ba..22561c96f63 100644
--- a/src/libstd/old_path/mod.rs
+++ b/src/libstd/old_path/mod.rs
@@ -144,12 +144,10 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     ///
     /// # Examples
     ///
-    /// ```
+    /// ```no_run
     /// # #![feature(old_path)]
-    /// use std::old_path::{Path, GenericPath};
-    /// # foo();
-    /// # #[cfg(windows)] fn foo() {}
-    /// # #[cfg(unix)] fn foo() {
+    /// # fn main() {
+    /// use std::old_path::Path;
     /// let path = Path::new("foo/bar");
     /// # }
     /// ```
@@ -170,12 +168,10 @@ pub trait GenericPath: Clone + GenericPathUnsafe {
     ///
     /// # Examples
     ///
-    /// ```
+    /// ```no_run
     /// # #![feature(old_path)]
-    /// use std::old_path::{Path, GenericPath};
-    /// # foo();
-    /// # #[cfg(windows)] fn foo() {}
-    /// # #[cfg(unix)] fn foo() {
+    /// # fn main() {
+    /// use std::old_path::Path;
     /// let x: &[u8] = b"foo\0";
     /// assert!(Path::new_opt(x).is_none());
     /// # }
diff --git a/src/libstd/process.rs b/src/libstd/process.rs
index 52f5965db80..36c0b3e466f 100644
--- a/src/libstd/process.rs
+++ b/src/libstd/process.rs
@@ -38,8 +38,6 @@ use thread;
 /// # Examples
 ///
 /// ```should_panic
-/// # #![feature(process)]
-///
 /// use std::process::Command;
 ///
 /// let output = Command::new("/bin/cat").arg("file.txt").output().unwrap_or_else(|e| {
@@ -267,10 +265,8 @@ impl Command {
     /// # Examples
     ///
     /// ```
-    /// # #![feature(process)]
     /// use std::process::Command;
-    ///
-    /// let output = Command::new("cat").arg("foot.txt").output().unwrap_or_else(|e| {
+    /// let output = Command::new("cat").arg("foo.txt").output().unwrap_or_else(|e| {
     ///     panic!("failed to execute process: {}", e)
     /// });
     ///
@@ -291,7 +287,6 @@ impl Command {
     /// # Examples
     ///
     /// ```
-    /// # #![feature(process)]
     /// use std::process::Command;
     ///
     /// let status = Command::new("ls").status().unwrap_or_else(|e| {
diff --git a/src/libstd/thread/mod.rs b/src/libstd/thread/mod.rs
index 5fe6e80d6e9..cd480f8c29e 100644
--- a/src/libstd/thread/mod.rs
+++ b/src/libstd/thread/mod.rs
@@ -99,6 +99,7 @@
 //! `println!` and `panic!` for the child thread:
 //!
 //! ```rust
+//! # #![allow(unused_must_use)]
 //! use std::thread;
 //!
 //! thread::Builder::new().name("child1".to_string()).spawn(move || {
-- 
cgit 1.4.1-3-g733a5


From 1b568ba0fd531ff33d45cb52d5c8cbfe1908be86 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Tue, 7 Apr 2015 17:15:58 -0700
Subject: std: Hide facade extension traits in docs

These traits are currently all just unstable parts of the facade which are
implementation details for primitives further up the facade. This may make it
more difficult to find what set of methods you get if only linking to libcore,
but for now that's also unstable behavior.

Closes #22025
---
 src/libcore/char.rs    | 1 +
 src/libcore/num/mod.rs | 1 +
 src/libcore/slice.rs   | 1 +
 src/libcore/str/mod.rs | 1 +
 4 files changed, 4 insertions(+)

(limited to 'src/libcore')

diff --git a/src/libcore/char.rs b/src/libcore/char.rs
index 010415b364a..ba9748eea71 100644
--- a/src/libcore/char.rs
+++ b/src/libcore/char.rs
@@ -139,6 +139,7 @@ pub fn from_digit(num: u32, radix: u32) -> Option<char> {
 // NB: the stabilization and documentation for this trait is in
 // unicode/char.rs, not here
 #[allow(missing_docs)] // docs in libunicode/u_char.rs
+#[doc(hidden)]
 pub trait CharExt {
     fn is_digit(self, radix: u32) -> bool;
     fn to_digit(self, radix: u32) -> Option<u32>;
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 28e0bcf13dd..2a194766834 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -2476,6 +2476,7 @@ pub enum FpCategory {
 //               `unused_self`. Removing it requires #8888 to be fixed.
 #[unstable(feature = "core",
            reason = "distribution of methods between core/std is unclear")]
+#[doc(hidden)]
 pub trait Float
     : Copy + Clone
     + NumCast
diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs
index 70e60adf64c..0e6acf0160d 100644
--- a/src/libcore/slice.rs
+++ b/src/libcore/slice.rs
@@ -63,6 +63,7 @@ use raw::Slice as RawSlice;
 
 /// Extension methods for slices.
 #[allow(missing_docs)] // docs in libcollections
+#[doc(hidden)]
 pub trait SliceExt {
     type Item;
 
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 5c8b6a774cd..9bc760b56ec 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -1496,6 +1496,7 @@ impl<'a, S: ?Sized> Str for &'a S where S: Str {
 
 /// Methods for string slices
 #[allow(missing_docs)]
+#[doc(hidden)]
 pub trait StrExt {
     // NB there are no docs here are they're all located on the StrExt trait in
     // libcollections, not here.
-- 
cgit 1.4.1-3-g733a5