Auto merge of #96094 - Elliot-Roberts:fix_doctests, r=compiler-errors

Begin fixing all the broken doctests in `compiler/` Begins to fix #95994. All of them pass now but 24 of them I've marked with `ignore HELP (<explanation>)` (asking for help) as I'm unsure how to get them to work / if we should leave them as they are. There are also a few that I marked `ignore` that could maybe be made to work but seem less important. Each `ignore` has a rough "reason" for ignoring after it parentheses, with - `(pseudo-rust)` meaning "mostly rust-like but contains foreign syntax" - `(illustrative)` a somewhat catchall for either a fragment of rust that doesn't stand on its own (like a lone type), or abbreviated rust with ellipses and undeclared types that would get too cluttered if made compile-worthy. - `(not-rust)` stuff that isn't rust but benefits from the syntax highlighting, like MIR. - `(internal)` uses `rustc_*` code which would be difficult to make work with the testing setup. Those reason notes are a bit inconsistently applied and messy though. If that's important I can go through them again and try a more principled approach. When I run `rg '```ignore \(' .` on the repo, there look to be lots of different conventions other people have used for this sort of thing. I could try unifying them all if that would be helpful. I'm not sure if there was a better existing way to do this but I wrote my own script to help me run all the doctests and wade through the output. If that would be useful to anyone else, I put it here: https://github.com/Elliot-Roberts/rust_doctest_fixing_tool
rust-lang · May 7, 2022 · 574830f · 574830f
2 parents 36aa7c1 + 647d0b6
commit 574830f
Show file tree

Hide file tree

Showing 116 changed files with 668 additions and 609 deletions.
diff --git a/compiler/rustc_ast/src/ast.rs b/compiler/rustc_ast/src/ast.rs
@@ -573,7 +573,7 @@ pub struct Block {
     pub span: Span,
     pub tokens: Option<LazyTokenStream>,
     /// The following *isn't* a parse error, but will cause multiple errors in following stages.
-    /// ```
+    /// ```compile_fail
     /// let x = {
     ///     foo: var
     /// };

diff --git a/compiler/rustc_ast_lowering/src/expr.rs b/compiler/rustc_ast_lowering/src/expr.rs
@@ -616,7 +616,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
     }
 
     /// Desugar `<expr>.await` into:
-    /// ```rust
+    /// ```ignore (pseudo-rust)
     /// match ::std::future::IntoFuture::into_future(<expr>) {
     ///     mut __awaitee => loop {
     ///         match unsafe { ::std::future::Future::poll(
@@ -1363,7 +1363,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
     }
 
     /// Desugar `ExprForLoop` from: `[opt_ident]: for <pat> in <head> <body>` into:
-    /// ```rust
+    /// ```ignore (pseudo-rust)
     /// {
     ///     let result = match IntoIterator::into_iter(<head>) {
     ///         mut iter => {
@@ -1474,7 +1474,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
     }
 
     /// Desugar `ExprKind::Try` from: `<expr>?` into:
-    /// ```rust
+    /// ```ignore (pseudo-rust)
     /// match Try::branch(<expr>) {
     ///     ControlFlow::Continue(val) => #[allow(unreachable_code)] val,,
     ///     ControlFlow::Break(residual) =>

diff --git a/compiler/rustc_ast_lowering/src/lib.rs b/compiler/rustc_ast_lowering/src/lib.rs
@@ -920,7 +920,7 @@ impl<'a, 'hir> LoweringContext<'a, 'hir> {
 
     /// Given an associated type constraint like one of these:
     ///
-    /// ```
+    /// ```ignore (illustrative)
     /// T: Iterator<Item: Debug>
     ///             ^^^^^^^^^^^
     /// T: Iterator<Item = Debug>

diff --git a/compiler/rustc_ast_pretty/src/pp.rs b/compiler/rustc_ast_pretty/src/pp.rs
@@ -68,20 +68,20 @@
 //! will be made to flow subsequent breaks together onto lines. Inconsistent
 //! is the opposite. Inconsistent breaking example would be, say:
 //!
-//! ```
+//! ```ignore (illustrative)
 //! foo(hello, there, good, friends)
 //! ```
 //!
 //! breaking inconsistently to become
 //!
-//! ```
+//! ```ignore (illustrative)
 //! foo(hello, there,
 //!     good, friends);
 //! ```
 //!
 //! whereas a consistent breaking would yield:
 //!
-//! ```
+//! ```ignore (illustrative)
 //! foo(hello,
 //!     there,
 //!     good,
@@ -153,14 +153,14 @@ enum IndentStyle {
     /// Vertically aligned under whatever column this block begins at.
     ///
     ///     fn demo(arg1: usize,
-    ///             arg2: usize);
+    ///             arg2: usize) {}
     Visual,
     /// Indented relative to the indentation level of the previous line.
     ///
     ///     fn demo(
     ///         arg1: usize,
     ///         arg2: usize,
-    ///     );
+    ///     ) {}
     Block { offset: isize },
 }
 

diff --git a/compiler/rustc_borrowck/src/diagnostics/conflict_errors.rs b/compiler/rustc_borrowck/src/diagnostics/conflict_errors.rs
@@ -896,20 +896,23 @@ impl<'cx, 'tcx> MirBorrowckCtxt<'cx, 'tcx> {
     ///
     /// In the simplest case, where there are no unions involved, if a mutable borrow of `x` is
     /// attempted while a shared borrow is live, then this function will return:
-    ///
-    ///     ("x", "", "")
-    ///
+    /// ```
+    /// ("x", "", "")
+    /// # ;
+    /// ```
     /// In the simple union case, if a mutable borrow of a union field `x.z` is attempted while
     /// a shared borrow of another field `x.y`, then this function will return:
-    ///
-    ///     ("x", "x.z", "x.y")
-    ///
+    /// ```
+    /// ("x", "x.z", "x.y")
+    /// # ;
+    /// ```
     /// In the more complex union case, where the union is a field of a struct, then if a mutable
     /// borrow of a union field in a struct `x.u.z` is attempted while a shared borrow of
     /// another field `x.u.y`, then this function will return:
-    ///
-    ///     ("x.u", "x.u.z", "x.u.y")
-    ///
+    /// ```
+    /// ("x.u", "x.u.z", "x.u.y")
+    /// # ;
+    /// ```
     /// This is used when creating error messages like below:
     ///
     /// ```text

diff --git a/compiler/rustc_borrowck/src/diagnostics/region_errors.rs b/compiler/rustc_borrowck/src/diagnostics/region_errors.rs
@@ -259,7 +259,7 @@ impl<'a, 'tcx> MirBorrowckCtxt<'a, 'tcx> {
     /// Report an error because the universal region `fr` was required to outlive
     /// `outlived_fr` but it is not known to do so. For example:
     ///
-    /// ```
+    /// ```compile_fail,E0312
     /// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
     /// ```
     ///

diff --git a/compiler/rustc_borrowck/src/diagnostics/region_name.rs b/compiler/rustc_borrowck/src/diagnostics/region_name.rs
@@ -210,7 +210,7 @@ impl<'tcx> MirBorrowckCtxt<'_, 'tcx> {
     /// Suppose we are trying to give a name to the lifetime of the
     /// reference `x`:
     ///
-    /// ```
+    /// ```ignore (pseudo-rust)
     /// fn foo(x: &u32) { .. }
     /// ```
     ///
@@ -746,7 +746,7 @@ impl<'tcx> MirBorrowckCtxt<'_, 'tcx> {
     /// e.g. given the function:
     ///
     /// ```
-    /// async fn foo() -> i32 {}
+    /// async fn foo() -> i32 { 2 }
     /// ```
     ///
     /// this function, given the lowered return type of `foo`, an [`OpaqueDef`] that implements `Future<Output=i32>`,

diff --git a/compiler/rustc_borrowck/src/member_constraints.rs b/compiler/rustc_borrowck/src/member_constraints.rs
@@ -169,7 +169,7 @@ where
     /// Returns the "choice regions" for a given member
     /// constraint. This is the `R1..Rn` from a constraint like:
     ///
-    /// ```
+    /// ```text
     /// R0 member of [R1..Rn]
     /// ```
     crate fn choice_regions(&self, pci: NllMemberConstraintIndex) -> &[ty::RegionVid] {
@@ -195,14 +195,14 @@ where
 ///
 /// Before:
 ///
-/// ```
+/// ```text
 /// target_list: A -> B -> C -> (None)
 /// source_list: D -> E -> F -> (None)
 /// ```
 ///
 /// After:
 ///
-/// ```
+/// ```text
 /// target_list: A -> B -> C -> D -> E -> F -> (None)
 /// ```
 fn append_list(

diff --git a/compiler/rustc_borrowck/src/region_infer/mod.rs b/compiler/rustc_borrowck/src/region_infer/mod.rs
@@ -436,14 +436,14 @@ impl<'tcx> RegionInferenceContext<'tcx> {
     /// minimum values.
     ///
     /// For example:
-    ///
-    ///     fn foo<'a, 'b>(..) where 'a: 'b
-    ///
+    /// ```
+    /// fn foo<'a, 'b>( /* ... */ ) where 'a: 'b { /* ... */ }
+    /// ```
     /// would initialize two variables like so:
-    ///
-    ///     R0 = { CFG, R0 } // 'a
-    ///     R1 = { CFG, R0, R1 } // 'b
-    ///
+    /// ```ignore (illustrative)
+    /// R0 = { CFG, R0 } // 'a
+    /// R1 = { CFG, R0, R1 } // 'b
+    /// ```
     /// Here, R0 represents `'a`, and it contains (a) the entire CFG
     /// and (b) any universally quantified regions that it outlives,
     /// which in this case is just itself. R1 (`'b`) in contrast also
@@ -1310,9 +1310,9 @@ impl<'tcx> RegionInferenceContext<'tcx> {
     /// whether any of the constraints were too strong. In particular,
     /// we want to check for a case where a universally quantified
     /// region exceeded its bounds. Consider:
-    ///
-    ///     fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
-    ///
+    /// ```compile_fail,E0312
+    /// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
+    /// ```
     /// In this case, returning `x` requires `&'a u32 <: &'b u32`
     /// and hence we establish (transitively) a constraint that
     /// `'a: 'b`. The `propagate_constraints` code above will
@@ -1366,9 +1366,9 @@ impl<'tcx> RegionInferenceContext<'tcx> {
     /// <https://smallcultfollowing.com/babysteps/blog/2019/01/17/polonius-and-region-errors/>
     ///
     /// In the canonical example
-    ///
-    ///     fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
-    ///
+    /// ```compile_fail,E0312
+    /// fn foo<'a, 'b>(x: &'a u32) -> &'b u32 { x }
+    /// ```
     /// returning `x` requires `&'a u32 <: &'b u32` and hence we establish (transitively) a
     /// constraint that `'a: 'b`. It is an error that we have no evidence that this
     /// constraint holds.

diff --git a/compiler/rustc_borrowck/src/type_check/mod.rs b/compiler/rustc_borrowck/src/type_check/mod.rs
@@ -971,7 +971,7 @@ pub enum Locations {
     /// things like the type of the return slot. Consider this
     /// example:
     ///
-    /// ```
+    /// ```compile_fail,E0515
     /// fn foo<'a>(x: &'a u32) -> &'a u32 {
     ///     let y = 22;
     ///     return &y; // error

diff --git a/compiler/rustc_borrowck/src/universal_regions.rs b/compiler/rustc_borrowck/src/universal_regions.rs
@@ -187,12 +187,12 @@ pub enum RegionClassification {
     ///
     /// Consider this example:
     ///
-    /// ```
+    /// ```ignore (pseudo-rust)
     /// fn foo<'a, 'b>(a: &'a u32, b: &'b u32, c: &'static u32) {
     ///   let closure = for<'x> |x: &'x u32| { .. };
-    ///                 ^^^^^^^ pretend this were legal syntax
-    ///                         for declaring a late-bound region in
-    ///                         a closure signature
+    ///    //           ^^^^^^^ pretend this were legal syntax
+    ///    //                   for declaring a late-bound region in
+    ///    //                   a closure signature
     /// }
     /// ```
     ///

diff --git a/compiler/rustc_builtin_macros/src/deriving/encodable.rs b/compiler/rustc_builtin_macros/src/deriving/encodable.rs
@@ -5,14 +5,14 @@
 //!
 //! For example, a type like:
 //!
-//! ```
+//! ```ignore (old code)
 //! #[derive(RustcEncodable, RustcDecodable)]
 //! struct Node { id: usize }
 //! ```
 //!
 //! would generate two implementations like:
 //!
-//! ```
+//! ```ignore (old code)
 //! # struct Node { id: usize }
 //! impl<S: Encoder<E>, E> Encodable<S, E> for Node {
 //!     fn encode(&self, s: &mut S) -> Result<(), E> {
@@ -40,7 +40,7 @@
 //! Other interesting scenarios are when the item has type parameters or
 //! references other non-built-in types. A type definition like:
 //!
-//! ```
+//! ```ignore (old code)
 //! # #[derive(RustcEncodable, RustcDecodable)]
 //! # struct Span;
 //! #[derive(RustcEncodable, RustcDecodable)]
@@ -49,7 +49,7 @@
 //!
 //! would yield functions like:
 //!
-//! ```
+//! ```ignore (old code)
 //! # #[derive(RustcEncodable, RustcDecodable)]
 //! # struct Span;
 //! # struct Spanned<T> { node: T, span: Span }

diff --git a/compiler/rustc_builtin_macros/src/deriving/generic/mod.rs b/compiler/rustc_builtin_macros/src/deriving/generic/mod.rs
@@ -1006,9 +1006,11 @@ impl<'a> MethodDef<'a> {
     ///         }
     ///     }
     /// }
-    ///
-    /// // or if A is repr(packed) - note fields are matched by-value
-    /// // instead of by-reference.
+    /// ```
+    /// or if A is repr(packed) - note fields are matched by-value
+    /// instead of by-reference.
+    /// ```
+    /// # struct A { x: i32, y: i32 }
     /// impl PartialEq for A {
     ///     fn eq(&self, other: &A) -> bool {
     ///         match *self {
@@ -1126,14 +1128,15 @@ impl<'a> MethodDef<'a> {
     /// // is equivalent to
     ///
     /// impl PartialEq for A {
-    ///     fn eq(&self, other: &A) -> ::bool {
+    ///     fn eq(&self, other: &A) -> bool {
+    ///         use A::*;
     ///         match (&*self, &*other) {
     ///             (&A1, &A1) => true,
     ///             (&A2(ref self_0),
     ///              &A2(ref __arg_1_0)) => (*self_0).eq(&(*__arg_1_0)),
     ///             _ => {
-    ///                 let __self_vi = match *self { A1(..) => 0, A2(..) => 1 };
-    ///                 let __arg_1_vi = match *other { A1(..) => 0, A2(..) => 1 };
+    ///                 let __self_vi = match *self { A1 => 0, A2(..) => 1 };
+    ///                 let __arg_1_vi = match *other { A1 => 0, A2(..) => 1 };
     ///                 false
     ///             }
     ///         }

diff --git a/compiler/rustc_builtin_macros/src/test_harness.rs b/compiler/rustc_builtin_macros/src/test_harness.rs
@@ -249,7 +249,7 @@ fn generate_test_harness(
 ///
 /// By default this expands to
 ///
-/// ```
+/// ```ignore UNSOLVED (I think I still need guidance for this one. Is it correct? Do we try to make it run? How do we nicely fill it out?)
 /// #[rustc_main]
 /// pub fn main() {
 ///     extern crate test;

diff --git a/compiler/rustc_codegen_llvm/src/back/lto.rs b/compiler/rustc_codegen_llvm/src/back/lto.rs
@@ -394,15 +394,15 @@ impl Drop for Linker<'_> {
 ///
 /// At a high level Thin LTO looks like:
 ///
-///     1. Prepare a "summary" of each LLVM module in question which describes
-///        the values inside, cost of the values, etc.
-///     2. Merge the summaries of all modules in question into one "index"
-///     3. Perform some global analysis on this index
-///     4. For each module, use the index and analysis calculated previously to
-///        perform local transformations on the module, for example inlining
-///        small functions from other modules.
-///     5. Run thin-specific optimization passes over each module, and then code
-///        generate everything at the end.
+///    1. Prepare a "summary" of each LLVM module in question which describes
+///       the values inside, cost of the values, etc.
+///    2. Merge the summaries of all modules in question into one "index"
+///    3. Perform some global analysis on this index
+///    4. For each module, use the index and analysis calculated previously to
+///       perform local transformations on the module, for example inlining
+///       small functions from other modules.
+///    5. Run thin-specific optimization passes over each module, and then code
+///       generate everything at the end.
 ///
 /// The summary for each module is intended to be quite cheap, and the global
 /// index is relatively quite cheap to create as well. As a result, the goal of

diff --git a/compiler/rustc_codegen_llvm/src/debuginfo/doc.md b/compiler/rustc_codegen_llvm/src/debuginfo/doc.md
@@ -27,9 +27,9 @@ The module is thus driven from an outside client with functions like
 Internally the module will try to reuse already created metadata by
 utilizing a cache. The way to get a shared metadata node when needed is
 thus to just call the corresponding function in this module:
-
-    let file_metadata = file_metadata(cx, file);
-
+```ignore (illustrative)
+let file_metadata = file_metadata(cx, file);
+```
 The function will take care of probing the cache for an existing node for
 that exact file path.
 
@@ -63,7 +63,7 @@ struct List {
 
 will generate the following callstack with a naive DFS algorithm:
 
-```
+```ignore (illustrative)
 describe(t = List)
   describe(t = i32)
   describe(t = Option<Box<List>>)

diff --git a/compiler/rustc_data_structures/src/frozen.rs b/compiler/rustc_data_structures/src/frozen.rs
@@ -23,7 +23,8 @@
 //! `computed` does not change accidentally (e.g. somebody might accidentally call
 //! `foo.computed.mutate()`). This is what `Frozen` is for. We can do the following:
 //!
-//! ```rust
+//! ```
+//! # struct Bar {}
 //! use rustc_data_structures::frozen::Frozen;
 //!
 //! struct Foo {

diff --git a/compiler/rustc_data_structures/src/obligation_forest/mod.rs b/compiler/rustc_data_structures/src/obligation_forest/mod.rs
@@ -202,7 +202,7 @@ impl<O> Node<O> {
 /// with this node.
 ///
 /// The non-`Error` state transitions are as follows.
-/// ```
+/// ```text
 /// (Pre-creation)
 ///  |
 ///  |     register_obligation_at() (called by process_obligations() and