Auto merge of #29544 - Ryman:reduce_doc_warnings, r=steveklabnik

Did this alphabetically, so I didn't see [how `std` was doing things](https://dxr.mozilla.org/rust/source/src/libstd/lib.rs#215) till I was nearly finished. If you prefer to add crate-level-whitelists like std instead of test-level, I can rebase with that strategy.

A number of these commits can probably be dropped as the crates don't have much to test, and are deprecated. Let me know which if any to drop! (can also squash after review if desired)

r? @steveklabnik

14 files changed, 48 insertions, 10 deletions

diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index 9fcc2b3412a..59b05c21d80 100644
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -76,6 +76,7 @@
 //! a trait method that was originally defined to take `&self`.
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! use std::cell::RefCell;
 //!
 //! struct Graph {
@@ -125,6 +126,7 @@
 //! }
 //!
 //! struct RcBox<T> {
+//! # #[allow(dead_code)]
 //!     value: T,
 //!     refcount: Cell<usize>
 //! }
@@ -776,6 +778,7 @@ impl<'b, T: ?Sized> DerefMut for RefMut<'b, T> {
 /// use std::cell::UnsafeCell;
 /// use std::marker::Sync;
 ///
+/// # #[allow(dead_code)]
 /// struct NotThreadSafe<T> {
 ///     value: UnsafeCell<T>,
 /// }
diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs
index 302c9d0c369..5458a7b9c38 100644
--- a/src/libcore/cmp.rs
+++ b/src/libcore/cmp.rs
@@ -140,8 +140,6 @@ impl Ordering {
     /// This method can be used to reverse a comparison:
     ///
     /// ```
-    /// use std::cmp::Ordering;
-    ///
     /// let mut data: &mut [_] = &mut [2, 10, 5, 8];
     ///
     /// // sort the array from largest to smallest.
@@ -263,8 +261,6 @@ pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {
     /// # Examples
     ///
     /// ```
-    /// use std::cmp::Ordering;
-    ///
     /// let result = 1.0 < 2.0;
     /// assert_eq!(result, true);
     ///
diff --git a/src/libcore/default.rs b/src/libcore/default.rs
index cbad72eae3d..12c4a5ca200 100644
--- a/src/libcore/default.rs
+++ b/src/libcore/default.rs
@@ -15,6 +15,7 @@
 //! that define a set of options:
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! struct SomeOptions {
 //!     foo: i32,
 //!     bar: f32,
@@ -24,6 +25,7 @@
 //! How can we define some default values? You can use `Default`:
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! #[derive(Default)]
 //! struct SomeOptions {
 //!     foo: i32,
@@ -40,6 +42,7 @@
 //! If you have your own type, you need to implement `Default` yourself:
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! enum Kind {
 //!     A,
 //!     B,
@@ -66,6 +69,7 @@
 //! If you want to override a particular option, but still retain the other defaults:
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! # #[derive(Default)]
 //! # struct SomeOptions {
 //! #     foo: i32,
@@ -88,6 +92,7 @@ use marker::Sized;
 /// # Examples
 ///
 /// ```
+/// # #[allow(dead_code)]
 /// #[derive(Default)]
 /// struct SomeOptions {
 ///     foo: i32,
@@ -114,6 +119,7 @@ pub trait Default: Sized {
     /// Making your own:
     ///
     /// ```
+    /// # #[allow(dead_code)]
     /// enum Kind {
     ///     A,
     ///     B,
diff --git a/src/libcore/hash/mod.rs b/src/libcore/hash/mod.rs
index 4e038f455e1..0899dc28848 100644
--- a/src/libcore/hash/mod.rs
+++ b/src/libcore/hash/mod.rs
@@ -45,6 +45,7 @@
 //!
 //! struct Person {
 //!     id: u32,
+//! # #[allow(dead_code)]
 //!     name: String,
 //!     phone: u64,
 //! }
diff --git a/src/libcore/intrinsics.rs b/src/libcore/intrinsics.rs
index ea4792bb495..a094bcd0192 100644
--- a/src/libcore/intrinsics.rs
+++ b/src/libcore/intrinsics.rs
@@ -334,6 +334,7 @@ extern "rust-intrinsic" {
     /// use std::mem;
     /// use std::ptr;
     ///
+    /// # #[allow(dead_code)]
     /// fn swap<T>(x: &mut T, y: &mut T) {
     ///     unsafe {
     ///         // Give ourselves some scratch space to work with
@@ -372,6 +373,7 @@ extern "rust-intrinsic" {
     /// ```
     /// use std::ptr;
     ///
+    /// # #[allow(dead_code)]
     /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
     ///     let mut dst = Vec::with_capacity(elts);
     ///     dst.set_len(elts);
diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index f8c6e3cfdd7..8558927e4ac 100644
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -241,6 +241,7 @@
 //! method calls a closure on each element it iterates over:
 //!
 //! ```
+//! # #![allow(unused_must_use)]
 //! let v = vec![1, 2, 3, 4, 5];
 //! v.iter().map(|x| println!("{}", x));
 //! ```
@@ -419,7 +420,7 @@ pub trait Iterator {
     ///
     /// ```
     /// // an infinite iterator has no upper bound
-    /// let iter = (0..);
+    /// let iter = 0..;
     ///
     /// assert_eq!((0, None), iter.size_hint());
     /// ```
@@ -709,6 +710,7 @@ pub trait Iterator {
     /// If you're doing some sort of side effect, prefer [`for`] to `map()`:
     ///
     /// ```
+    /// # #![allow(unused_must_use)]
     /// // don't do this:
     /// (0..5).map(|x| println!("{}", x));
     ///
@@ -2695,7 +2697,7 @@ impl<'a, I: DoubleEndedIterator + ?Sized> DoubleEndedIterator for &'a mut I {
 ///
 /// ```
 /// // a finite range knows exactly how many times it will iterate
-/// let five = (0..5);
+/// let five = 0..5;
 ///
 /// assert_eq!(5, five.len());
 /// ```
@@ -2761,7 +2763,7 @@ pub trait ExactSizeIterator: Iterator {
     ///
     /// ```
     /// // a finite range knows exactly how many times it will iterate
-    /// let five = (0..5);
+    /// let five = 0..5;
     ///
     /// assert_eq!(5, five.len());
     /// ```
diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs
index 94408072932..df7b7c437c3 100644
--- a/src/libcore/lib.rs
+++ b/src/libcore/lib.rs
@@ -60,7 +60,7 @@
        html_root_url = "https://doc.rust-lang.org/nightly/",
        html_playground_url = "https://play.rust-lang.org/",
        issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")]
-#![doc(test(no_crate_inject))]
+#![doc(test(no_crate_inject, attr(allow(unused_variables), deny(warnings))))]
 
 #![no_core]
 #![allow(raw_pointer_derive)]
diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs
index a4a2552025b..bc8656b32b8 100644
--- a/src/libcore/macros.rs
+++ b/src/libcore/macros.rs
@@ -247,6 +247,7 @@ macro_rules! writeln {
 /// Match arms:
 ///
 /// ```
+/// # #[allow(dead_code)]
 /// fn foo(x: Option<i32>) {
 ///     match x {
 ///         Some(n) if n >= 0 => println!("Some(Non-negative)"),
@@ -260,6 +261,7 @@ macro_rules! writeln {
 /// Iterators:
 ///
 /// ```
+/// # #[allow(dead_code)]
 /// 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/libcore/marker.rs b/src/libcore/marker.rs
index 2f2dcc41a1c..6e6ae618527 100644
--- a/src/libcore/marker.rs
+++ b/src/libcore/marker.rs
@@ -42,6 +42,7 @@ impl<T> !Send for *mut T { }
 /// `?Sized` can be used to remove this bound if it is not appropriate.
 ///
 /// ```
+/// # #![allow(dead_code)]
 /// struct Foo<T>(T);
 /// struct Bar<T: ?Sized>(T);
 ///
@@ -106,6 +107,7 @@ pub trait Unsize<T: ?Sized> {
 /// `struct` can be `Copy`:
 ///
 /// ```
+/// # #[allow(dead_code)]
 /// struct Point {
 ///    x: i32,
 ///    y: i32,
@@ -115,6 +117,7 @@ pub trait Unsize<T: ?Sized> {
 /// A `struct` can be `Copy`, and `i32` is `Copy`, so therefore, `Point` is eligible to be `Copy`.
 ///
 /// ```
+/// # #![allow(dead_code)]
 /// # struct Point;
 /// struct PointList {
 ///     points: Vec<Point>,
@@ -303,6 +306,7 @@ macro_rules! impls{
 /// ```
 /// use std::marker::PhantomData;
 ///
+/// # #[allow(dead_code)]
 /// struct Slice<'a, T:'a> {
 ///     start: *const T,
 ///     end: *const T,
@@ -323,6 +327,7 @@ macro_rules! impls{
 /// mismatches by enforcing types in the method implementations:
 ///
 /// ```
+/// # #![allow(dead_code)]
 /// # trait ResType { fn foo(&self); }
 /// # struct ParamType;
 /// # mod foreign_lib {
@@ -393,6 +398,8 @@ mod impls {
 /// #![feature(reflect_marker)]
 /// use std::marker::Reflect;
 /// use std::any::Any;
+///
+/// # #[allow(dead_code)]
 /// fn foo<T:Reflect+'static>(x: &T) {
 ///     let any: &Any = x;
 ///     if any.is::<u32>() { println!("u32"); }
diff --git a/src/libcore/mem.rs b/src/libcore/mem.rs
index a87d135e425..2f01ea38340 100644
--- a/src/libcore/mem.rs
+++ b/src/libcore/mem.rs
@@ -92,6 +92,7 @@ pub use intrinsics::transmute;
 /// use std::mem;
 /// use std::ptr;
 ///
+/// # #[allow(dead_code)]
 /// fn swap<T>(x: &mut T, y: &mut T) {
 ///     unsafe {
 ///         // Give ourselves some scratch space to work with
@@ -151,6 +152,7 @@ pub fn size_of_val<T: ?Sized>(val: &T) -> usize {
 /// # Examples
 ///
 /// ```
+/// # #![allow(deprecated)]
 /// use std::mem;
 ///
 /// assert_eq!(4, mem::min_align_of::<i32>());
@@ -167,6 +169,7 @@ pub fn min_align_of<T>() -> usize {
 /// # Examples
 ///
 /// ```
+/// # #![allow(deprecated)]
 /// use std::mem;
 ///
 /// assert_eq!(4, mem::min_align_of_val(&5i32));
@@ -414,6 +417,7 @@ pub fn swap<T>(x: &mut T, y: &mut T) {
 /// `self`, allowing it to be returned:
 ///
 /// ```
+/// # #![allow(dead_code)]
 /// use std::mem;
 /// # struct Buffer<T> { buf: Vec<T> }
 /// impl<T> Buffer<T> {
diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs
index 1bfdafa7133..7ad49eef8f7 100644
--- a/src/libcore/ops.rs
+++ b/src/libcore/ops.rs
@@ -947,6 +947,7 @@ shr_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo += Foo;
@@ -996,6 +997,7 @@ add_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo -= Foo;
@@ -1045,6 +1047,7 @@ sub_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo *= Foo;
@@ -1094,6 +1097,7 @@ mul_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo /= Foo;
@@ -1143,6 +1147,7 @@ div_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo %= Foo;
@@ -1192,6 +1197,7 @@ rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo &= Foo;
@@ -1241,6 +1247,7 @@ bitand_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo |= Foo;
@@ -1290,6 +1297,7 @@ bitor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo ^= Foo;
@@ -1339,6 +1347,7 @@ bitxor_assign_impl! { bool usize u8 u16 u32 u64 isize i8 i16 i32 i64 }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo <<= Foo;
@@ -1407,6 +1416,7 @@ shl_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
 ///     }
 /// }
 ///
+/// # #[allow(unused_assignments)]
 /// fn main() {
 ///     let mut foo = Foo;
 ///     foo >>= Foo;
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index 26e00867d84..7a3b83f68d0 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -275,6 +275,7 @@ impl<T> Option<T> {
     ///
     /// ```
     /// #![feature(as_slice)]
+    /// # #![allow(deprecated)]
     ///
     /// let mut x = Some("Diamonds");
     /// {
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index 71219155cc3..6e1f120a1db 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -16,6 +16,7 @@
 //! and containing an error value.
 //!
 //! ```
+//! # #[allow(dead_code)]
 //! enum Result<T, E> {
 //!    Ok(T),
 //!    Err(E)
@@ -104,6 +105,7 @@
 //! something like this:
 //!
 //! ```no_run
+//! # #![allow(unused_must_use)] // \o/
 //! use std::fs::File;
 //! use std::io::prelude::*;
 //!
@@ -143,6 +145,7 @@
 //! # use std::fs::File;
 //! # use std::io::prelude::*;
 //! # use std::io;
+//! # #[allow(dead_code)]
 //! fn write_message() -> io::Result<()> {
 //!     let mut file = try!(File::create("valuable_data.txt"));
 //!     try!(file.write_all(b"important message"));
@@ -160,6 +163,7 @@
 //! It replaces this:
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! use std::fs::File;
 //! use std::io::prelude::*;
 //! use std::io;
@@ -189,6 +193,7 @@
 //! With this:
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! use std::fs::File;
 //! use std::io::prelude::*;
 //! use std::io;
@@ -422,6 +427,7 @@ impl<T, E> Result<T, E> {
     ///
     /// ```
     /// #![feature(as_slice)]
+    /// # #![allow(deprecated)]
     ///
     /// let mut x: Result<&str, u32> = Ok("Gold");
     /// {
diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs
index 18334ba91c6..7954bc3a0bf 100644
--- a/src/libcore/str/mod.rs
+++ b/src/libcore/str/mod.rs
@@ -142,8 +142,6 @@ impl Utf8Error {
     /// Basic usage:
     ///
     /// ```
-    /// #![feature(utf8_error)]
-    ///
     /// use std::str;
     ///
     /// // some invalid bytes, in a vector