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

mk/tests.mk

@@ -25,7 +25,8 @@ $(eval $(call RUST_CRATE,collectionstest))
 TEST_TARGET_CRATES = $(filter-out core rustc_unicode alloc_system libc \
 		     		  alloc_jemalloc,$(TARGET_CRATES)) \
 			collectionstest coretest
-TEST_DOC_CRATES = $(DOC_CRATES)
+TEST_DOC_CRATES = $(DOC_CRATES) arena flate fmt_macros getopts graphviz \
+                log rand rbml serialize syntax term test
 TEST_HOST_CRATES = $(filter-out rustc_typeck rustc_borrowck rustc_resolve \
 		   		rustc_trans rustc_lint,\
                      $(HOST_CRATES))

src/doc/trpl/documentation.md

@@ -620,6 +620,18 @@ You can control a few aspects of the HTML that `rustdoc` generates through the
 
 This sets a few different options, with a logo, favicon, and a root URL.
 
+### Configuring documentation tests
+
+You can also configure the way that `rustdoc` tests your documentation examples
+through the `#![doc(test(..))]` attribute.
+
+```rust
+#![doc(test(attr(allow(unused_variables), deny(warnings))))]
+```
+
+This allows unused variables within the examples, but will fail the test for any
+other lint warning thrown.
+
 ## Generation options
 
 `rustdoc` also contains a few other options on the command line, for further customization:

src/liballoc/lib.rs

@@ -70,7 +70,7 @@
        html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
        html_root_url = "https://doc.rust-lang.org/nightly/",
        issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
-       test(no_crate_inject))]
+       test(no_crate_inject, attr(allow(unused_variables), deny(warnings))))]
 #![no_std]
 #![cfg_attr(not(stage0), needs_allocator)]
 

src/libarena/lib.rs

@@ -28,7 +28,8 @@
 #![crate_type = "dylib"]
 #![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
        html_favicon_url = "https://doc.rust-lang.org/favicon.ico",
-       html_root_url = "https://doc.rust-lang.org/nightly/")]
+       html_root_url = "https://doc.rust-lang.org/nightly/",
+       test(no_crate_inject, attr(deny(warnings))))]
 
 #![feature(alloc)]
 #![feature(box_syntax)]

src/libcollections/binary_heap.rs

@@ -233,6 +233,7 @@ impl<T: Ord> BinaryHeap<T> {
     ///
     /// ```
     /// #![feature(binary_heap_extras)]
+    /// # #![allow(deprecated)]
     ///
     /// use std::collections::BinaryHeap;
     /// let heap = BinaryHeap::from_vec(vec![9, 1, 2, 7, 3, 2]);

src/libcollections/borrow.rs

@@ -72,6 +72,7 @@ impl<T> ToOwned for T where T: Clone {
 /// ```
 /// use std::borrow::Cow;
 ///
+/// # #[allow(dead_code)]
 /// fn abs_all(input: &mut Cow<[i32]>) {
 ///     for i in 0..input.len() {
 ///         let v = input[i];

src/libcollections/btree/set.rs

@@ -89,6 +89,7 @@ impl<T: Ord> BTreeSet<T> {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(unused_mut)]
     /// use std::collections::BTreeSet;
     ///
     /// let mut set: BTreeSet<i32> = BTreeSet::new();

src/libcollections/fmt.rs

@@ -150,6 +150,7 @@
 //! implement a method of the signature:
 //!
 //! ```
+//! # #![allow(dead_code)]
 //! # use std::fmt;
 //! # struct Foo; // our custom type
 //! # impl fmt::Display for Foo {
@@ -174,7 +175,6 @@
 //! like:
 //!
 //! ```
-//! #![feature(fmt_flags)]
 //! use std::fmt;
 //!
 //! #[derive(Debug)]
@@ -288,6 +288,7 @@
 //! off, some example usage is:
 //!
 //! ```
+//! # #![allow(unused_must_use)]
 //! use std::fmt;
 //! use std::io::{self, Write};
 //!

src/libcollections/lib.rs

@@ -27,7 +27,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/",
-       test(no_crate_inject))]
+       test(no_crate_inject, attr(allow(unused_variables), deny(warnings))))]
 
 #![allow(trivial_casts)]
 #![cfg_attr(test, allow(deprecated))] // rand

src/libcollections/slice.rs

@@ -852,6 +852,7 @@ pub trait SliceConcatExt<T: ?Sized> {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(deprecated)]
     /// assert_eq!(["hello", "world"].connect(" "), "hello world");
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/str.rs

@@ -298,7 +298,7 @@ impl str {
     /// done by `.chars()` or `.char_indices()`.
     ///
     /// ```
-    /// #![feature(str_char, core)]
+    /// #![feature(str_char)]
     ///
     /// use std::str::CharRange;
     ///
@@ -358,7 +358,7 @@ impl str {
     /// done by `.chars().rev()` or `.char_indices()`.
     ///
     /// ```
-    /// #![feature(str_char, core)]
+    /// #![feature(str_char)]
     ///
     /// use std::str::CharRange;
     ///
@@ -634,6 +634,7 @@ impl str {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(deprecated)]
     /// let four_lines = "foo\r\nbar\n\r\nbaz";
     /// let v: Vec<&str> = four_lines.lines_any().collect();
     ///
@@ -643,6 +644,7 @@ impl str {
     /// Leaving off the trailing character:
     ///
     /// ```
+    /// # #![allow(deprecated)]
     /// let four_lines = "foo\r\nbar\n\r\nbaz\n";
     /// let v: Vec<&str> = four_lines.lines_any().collect();
     ///
@@ -1179,8 +1181,6 @@ impl str {
     /// # Examples
     ///
     /// ```
-    /// #![feature(str_match_indices)]
-    ///
     /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
     /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
     ///
@@ -1216,8 +1216,6 @@ impl str {
     /// # Examples
     ///
     /// ```
-    /// #![feature(str_match_indices)]
-    ///
     /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
     /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
     ///

src/libcollections/string.rs

@@ -55,6 +55,7 @@ impl String {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(unused_mut)]
     /// let mut s = String::new();
     /// ```
     #[inline]
@@ -73,6 +74,20 @@ impl String {
     ///
     /// ```
     /// let mut s = String::with_capacity(10);
+    ///
+    /// // The String contains no chars, even though it has capacity for more
+    /// assert_eq!(s.len(), 0);
+    ///
+    /// // These are all done without reallocating...
+    /// let cap = s.capacity();
+    /// for i in 0..10 {
+    ///     s.push('a');
+    /// }
+    ///
+    /// assert_eq!(s.capacity(), cap);
+    ///
+    /// // ...but this may make the vector reallocate
+    /// s.push('a');
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]

src/libcollections/vec.rs

@@ -242,6 +242,7 @@ impl<T> Vec<T> {
     /// # Examples
     ///
     /// ```
+    /// # #![allow(unused_mut)]
     /// let mut vec: Vec<i32> = Vec::new();
     /// ```
     #[inline]

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>,
 /// }

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);
     ///

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,

src/libcore/hash/mod.rs

@@ -45,6 +45,7 @@
 //!
 //! struct Person {
 //!     id: u32,
+//! # #[allow(dead_code)]
 //!     name: String,
 //!     phone: u64,
 //! }

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);

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());
     /// ```

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)]

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"); }