Rollup merge of rust-lang#42777 - kennytm:kill-ignore-doctest, r=este…

…bank

Remove most "```ignore" doc tests.

Unconditional ` ```ignore ` doc tests lead to outdated examples (e.g. rust-lang#42729 (comment)). This PR tries to change all existing ` ```ignore ` tests into one of the following:

* Add import and declarations to ensure the code is run-pass
* If the code is not Rust, change to ` ```text `/` ```sh `/` ```json `/` ```dot `
* If the code is expected compile-fail, change to ` ```compile_fail `
* If the code is expected run-fail, change to ` ```should_panic `
* If the code can type-check but cannot link/run, change to ` ```no_run `
* Otherwise, add an explanation after the ` ```ignore `

The `--explain` handling is changed to cope with hidden lines from the error index.

Tidy is changed to reject any unexplained ` ```ignore ` and ` ```rust,ignore `.

src/liballoc/boxed.rs

@@ -42,8 +42,10 @@
 //! Recursive structures must be boxed, because if the definition of `Cons`
 //! looked like this:
 //!
-//! ```rust,ignore
+//! ```compile_fail,E0072
+//! # enum List<T> {
 //! Cons(T, List<T>),
+//! # }
 //! ```
 //!
 //! It wouldn't work. This is because the size of a `List` depends on how many

src/liballoc/fmt.rs

@@ -230,7 +230,7 @@
 //! There are a number of related macros in the `format!` family. The ones that
 //! are currently implemented are:
 //!
-//! ```ignore
+//! ```ignore (only-for-syntax-highlight)
 //! format!      // described above
 //! write!       // first argument is a &mut io::Write, the destination
 //! writeln!     // same as write but appends a newline

src/liballoc/raw_vec.rs

@@ -244,7 +244,11 @@ impl<T, A: Alloc> RawVec<T, A> {
     ///
     /// # Examples
     ///
-    /// ```ignore
+    /// ```
+    /// # #![feature(alloc)]
+    /// # extern crate alloc;
+    /// # use std::ptr;
+    /// # use alloc::raw_vec::RawVec;
     /// struct MyVec<T> {
     ///     buf: RawVec<T>,
     ///     len: usize,
@@ -261,6 +265,10 @@ impl<T, A: Alloc> RawVec<T, A> {
     ///         self.len += 1;
     ///     }
     /// }
+    /// # fn main() {
+    /// #   let mut vec = MyVec { buf: RawVec::new(), len: 0 };
+    /// #   vec.push(1);
+    /// # }
     /// ```
     #[inline(never)]
     #[cold]
@@ -440,13 +448,17 @@ impl<T, A: Alloc> RawVec<T, A> {
     ///
     /// # Examples
     ///
-    /// ```ignore
+    /// ```
+    /// # #![feature(alloc)]
+    /// # extern crate alloc;
+    /// # use std::ptr;
+    /// # use alloc::raw_vec::RawVec;
     /// struct MyVec<T> {
     ///     buf: RawVec<T>,
     ///     len: usize,
     /// }
     ///
-    /// impl<T> MyVec<T> {
+    /// impl<T: Clone> MyVec<T> {
     ///     pub fn push_all(&mut self, elems: &[T]) {
     ///         self.buf.reserve(self.len, elems.len());
     ///         // reserve would have aborted or panicked if the len exceeded
@@ -459,6 +471,10 @@ impl<T, A: Alloc> RawVec<T, A> {
     ///         }
     ///     }
     /// }
+    /// # fn main() {
+    /// #   let mut vector = MyVec { buf: RawVec::new(), len: 0 };
+    /// #   vector.push_all(&[1, 3, 5, 7, 9]);
+    /// # }
     /// ```
     pub fn reserve(&mut self, used_cap: usize, needed_extra_cap: usize) {
         unsafe {

src/liballoc/string.rs

@@ -124,7 +124,7 @@ use boxed::Box;
 /// similar, but without the UTF-8 constraint. The second implication is that
 /// you cannot index into a `String`:
 ///
-/// ```ignore
+/// ```compile_fail,E0277
 /// let s = "hello";
 ///
 /// println!("The first letter of s is {}", s[0]); // ERROR!!!

src/liballoc/vec.rs

@@ -156,7 +156,7 @@ use Bound::{Excluded, Included, Unbounded};
 /// However be careful: if you try to access an index which isn't in the `Vec`,
 /// your software will panic! You cannot do this:
 ///
-/// ```ignore
+/// ```should_panic
 /// let v = vec![0, 2, 4, 6];
 /// println!("{}", v[6]); // it will panic!
 /// ```

src/libcore/iter/mod.rs

@@ -211,7 +211,7 @@
 //! There's one more subtle bit here: the standard library contains an
 //! interesting implementation of [`IntoIterator`]:
 //!
-//! ```ignore
+//! ```ignore (only-for-syntax-highlight)
 //! impl<I: Iterator> IntoIterator for I
 //! ```
 //!

src/libcore/marker.rs

@@ -434,7 +434,7 @@ macro_rules! impls{
 /// example, here is a struct `Slice` that has two pointers of type `*const T`,
 /// presumably pointing into an array somewhere:
 ///
-/// ```ignore
+/// ```compile_fail,E0392
 /// struct Slice<'a, T> {
 ///     start: *const T,
 ///     end: *const T,

src/libcore/mem.rs

@@ -328,11 +328,18 @@ pub fn align_of_val<T: ?Sized>(val: &T) -> usize {
 ///
 /// Here's an example of how a collection might make use of needs_drop:
 ///
-/// ```ignore
+/// ```
 /// #![feature(needs_drop)]
 /// use std::{mem, ptr};
 ///
-/// pub struct MyCollection<T> { /* ... */ }
+/// pub struct MyCollection<T> {
+/// #   data: [T; 1],
+///     /* ... */
+/// }
+/// # impl<T> MyCollection<T> {
+/// #   fn iter_mut(&mut self) -> &mut [T] { &mut self.data }
+/// #   fn free_buffer(&mut self) {}
+/// # }
 ///
 /// impl<T> Drop for MyCollection<T> {
 ///     fn drop(&mut self) {
@@ -575,7 +582,7 @@ pub fn swap<T>(x: &mut T, y: &mut T) {
 /// `replace` allows consumption of a struct field by replacing it with another value.
 /// Without `replace` you can run into issues like these:
 ///
-/// ```ignore
+/// ```compile_fail,E0507
 /// struct Buffer<T> { buf: Vec<T> }
 ///
 /// impl<T> Buffer<T> {
@@ -645,7 +652,7 @@ pub fn replace<T>(dest: &mut T, mut src: T) -> T {
 ///
 /// Borrows are based on lexical scope, so this produces an error:
 ///
-/// ```ignore
+/// ```compile_fail,E0502
 /// let mut v = vec![1, 2, 3];
 /// let x = &v[0];
 ///

src/libcore/ops/place.rs

@@ -38,7 +38,13 @@ pub trait Place<Data: ?Sized> {
 ///
 /// `PLACE <- EXPR` effectively desugars into:
 ///
-/// ```rust,ignore
+/// ```
+/// # #![feature(placement_new_protocol, box_heap)]
+/// # use std::ops::{Placer, Place, InPlace};
+/// # #[allow(non_snake_case)]
+/// # fn main() {
+/// # let PLACE = std::boxed::HEAP;
+/// # let EXPR = 1;
 /// let p = PLACE;
 /// let mut place = Placer::make_place(p);
 /// let raw_place = Place::pointer(&mut place);
@@ -47,6 +53,7 @@ pub trait Place<Data: ?Sized> {
 ///     std::ptr::write(raw_place, value);
 ///     InPlace::finalize(place)
 /// }
+/// # ; }
 /// ```
 ///
 /// The type of `PLACE <- EXPR` is derived from the type of `PLACE`;
@@ -89,14 +96,21 @@ pub trait InPlace<Data: ?Sized>: Place<Data> {
 ///
 /// `box EXPR` effectively desugars into:
 ///
-/// ```rust,ignore
+/// ```
+/// # #![feature(placement_new_protocol)]
+/// # use std::ops::{BoxPlace, Place, Boxed};
+/// # #[allow(non_snake_case)]
+/// # fn main() {
+/// # let EXPR = 1;
 /// let mut place = BoxPlace::make_place();
 /// let raw_place = Place::pointer(&mut place);
 /// let value = EXPR;
+/// # let _: Box<_> =
 /// unsafe {
 ///     ::std::ptr::write(raw_place, value);
 ///     Boxed::finalize(place)
 /// }
+/// # ; }
 /// ```
 ///
 /// The type of `box EXPR` is supplied from its surrounding

src/libcore/ops/range.rs

@@ -26,7 +26,7 @@ use fmt;
 /// It does not have an `IntoIterator` implementation, so you can't use it in a
 /// `for` loop directly. This won't compile:
 ///
-/// ```ignore
+/// ```compile_fail,E0277
 /// for i in .. {
 ///    // ...
 /// }
@@ -184,7 +184,7 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
 /// It does not have an `IntoIterator` implementation, so you can't use it in a
 /// `for` loop directly. This won't compile:
 ///
-/// ```ignore
+/// ```compile_fail,E0277
 /// for i in ..5 {
 ///     // ...
 /// }
@@ -313,7 +313,8 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
 /// It does not have an `IntoIterator` implementation, so you can't use it in a
 /// `for` loop directly. This won't compile:
 ///
-/// ```ignore
+/// ```compile_fail,E0277
+/// #![feature(inclusive_range_syntax)]
 /// for i in ...5 {
 ///     // ...
 /// }

src/libcore/panicking.rs

@@ -15,8 +15,10 @@
 //! useful an upstream crate must define panicking for libcore to use. The current
 //! interface for panicking is:
 //!
-//! ```ignore
-//! fn panic_impl(fmt: fmt::Arguments, &(&'static str, u32)) -> !;
+//! ```
+//! # use std::fmt;
+//! fn panic_impl(fmt: fmt::Arguments, file_line: &(&'static str, u32)) -> !
+//! # { loop {} }
 //! ```
 //!
 //! This definition allows for panicking with any general message, but it does not

src/libcore/ptr.rs

@@ -408,11 +408,11 @@ impl<T: ?Sized> *const T {
     ///
     /// Basic usage:
     ///
-    /// ```ignore
-    /// let val: *const u8 = &10u8 as *const u8;
+    /// ```
+    /// let ptr: *const u8 = &10u8 as *const u8;
     ///
     /// unsafe {
-    ///     if let Some(val_back) = val.as_ref() {
+    ///     if let Some(val_back) = ptr.as_ref() {
     ///         println!("We got back the value: {}!", val_back);
     ///     }
     /// }
@@ -570,11 +570,11 @@ impl<T: ?Sized> *mut T {
     ///
     /// Basic usage:
     ///
-    /// ```ignore
-    /// let val: *mut u8 = &mut 10u8 as *mut u8;
+    /// ```
+    /// let ptr: *mut u8 = &mut 10u8 as *mut u8;
     ///
     /// unsafe {
-    ///     if let Some(val_back) = val.as_ref() {
+    ///     if let Some(val_back) = ptr.as_ref() {
     ///         println!("We got back the value: {}!", val_back);
     ///     }
     /// }

src/libgraphviz/lib.rs

@@ -111,7 +111,7 @@
 //!
 //! Output from first example (in `example1.dot`):
 //!
-//! ```ignore
+//! ```dot
 //! digraph example1 {
 //!     N0[label="N0"];
 //!     N1[label="N1"];