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

5 files changed, 28 insertions, 45 deletions

diff --git a/compiler/rustc_data_structures/src/frozen.rs b/compiler/rustc_data_structures/src/frozen.rs
index 2daf5b04141..c81e1b124f0 100644
--- 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
index 5fe2a1fb84b..74f432a7967 100644
--- 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
diff --git a/compiler/rustc_data_structures/src/owning_ref/mod.rs b/compiler/rustc_data_structures/src/owning_ref/mod.rs
index e7397bf13ba..ed5e566184f 100644
--- a/compiler/rustc_data_structures/src/owning_ref/mod.rs
+++ b/compiler/rustc_data_structures/src/owning_ref/mod.rs
@@ -25,9 +25,8 @@ of the reference because the backing allocation of the vector does not change.
 This library enables this safe usage by keeping the owner and the reference
 bundled together in a wrapper type that ensure that lifetime constraint:
 
-```rust
-# extern crate owning_ref;
-# use owning_ref::OwningRef;
+```
+# use rustc_data_structures::owning_ref::OwningRef;
 # fn main() {
 fn return_owned_and_referenced() -> OwningRef<Vec<u8>, [u8]> {
     let v = vec![1, 2, 3, 4];
@@ -56,8 +55,7 @@ See the documentation around `OwningHandle` for more details.
 ## Basics
 
 ```
-extern crate owning_ref;
-use owning_ref::BoxRef;
+use rustc_data_structures::owning_ref::BoxRef;
 
 fn main() {
     // Create an array owned by a Box.
@@ -78,8 +76,7 @@ fn main() {
 ## Caching a reference to a struct field
 
 ```
-extern crate owning_ref;
-use owning_ref::BoxRef;
+use rustc_data_structures::owning_ref::BoxRef;
 
 fn main() {
     struct Foo {
@@ -106,8 +103,7 @@ fn main() {
 ## Caching a reference to an entry in a vector
 
 ```
-extern crate owning_ref;
-use owning_ref::VecRef;
+use rustc_data_structures::owning_ref::VecRef;
 
 fn main() {
     let v = VecRef::new(vec![1, 2, 3, 4, 5]).map(|v| &v[3]);
@@ -118,8 +114,7 @@ fn main() {
 ## Caching a subslice of a String
 
 ```
-extern crate owning_ref;
-use owning_ref::StringRef;
+use rustc_data_structures::owning_ref::StringRef;
 
 fn main() {
     let s = StringRef::new("hello world".to_owned())
@@ -132,8 +127,7 @@ fn main() {
 ## Reference counted slices that share ownership of the backing storage
 
 ```
-extern crate owning_ref;
-use owning_ref::RcRef;
+use rustc_data_structures::owning_ref::RcRef;
 use std::rc::Rc;
 
 fn main() {
@@ -155,8 +149,7 @@ fn main() {
 ## Atomic reference counted slices that share ownership of the backing storage
 
 ```
-extern crate owning_ref;
-use owning_ref::ArcRef;
+use rustc_data_structures::owning_ref::ArcRef;
 use std::sync::Arc;
 
 fn main() {
@@ -188,8 +181,7 @@ fn main() {
 ## References into RAII locks
 
 ```
-extern crate owning_ref;
-use owning_ref::RefRef;
+use rustc_data_structures::owning_ref::RefRef;
 use std::cell::{RefCell, Ref};
 
 fn main() {
@@ -219,8 +211,7 @@ When the owned container implements `DerefMut`, it is also possible to make
 a _mutable owning reference_. (e.g., with `Box`, `RefMut`, `MutexGuard`)
 
 ```
-extern crate owning_ref;
-use owning_ref::RefMutRefMut;
+use rustc_data_structures::owning_ref::RefMutRefMut;
 use std::cell::{RefCell, RefMut};
 
 fn main() {
@@ -326,8 +317,7 @@ impl<O, T: ?Sized> OwningRef<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRef;
+    /// use rustc_data_structures::owning_ref::OwningRef;
     ///
     /// fn main() {
     ///     let owning_ref = OwningRef::new(Box::new(42));
@@ -362,8 +352,7 @@ impl<O, T: ?Sized> OwningRef<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRef;
+    /// use rustc_data_structures::owning_ref::OwningRef;
     ///
     /// fn main() {
     ///     let owning_ref = OwningRef::new(Box::new([1, 2, 3, 4]));
@@ -390,8 +379,7 @@ impl<O, T: ?Sized> OwningRef<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRef;
+    /// use rustc_data_structures::owning_ref::OwningRef;
     ///
     /// fn main() {
     ///     let owning_ref = OwningRef::new(Box::new([1, 2, 3, 4]));
@@ -441,8 +429,7 @@ impl<O, T: ?Sized> OwningRef<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::{OwningRef, Erased};
+    /// use rustc_data_structures::owning_ref::{OwningRef, Erased};
     ///
     /// fn main() {
     ///     // N.B., using the concrete types here for explicitness.
@@ -460,7 +447,7 @@ impl<O, T: ?Sized> OwningRef<O, T> {
     ///     let owning_ref_b: OwningRef<Box<Vec<(i32, bool)>>, i32>
     ///         = owning_ref_b.map(|a| &a[1].0);
     ///
-    ///     let owning_refs: [OwningRef<Box<Erased>, i32>; 2]
+    ///     let owning_refs: [OwningRef<Box<dyn Erased>, i32>; 2]
     ///         = [owning_ref_a.erase_owner(), owning_ref_b.erase_owner()];
     ///
     ///     assert_eq!(*owning_refs[0], 1);
@@ -516,8 +503,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRefMut;
+    /// use rustc_data_structures::owning_ref::OwningRefMut;
     ///
     /// fn main() {
     ///     let owning_ref_mut = OwningRefMut::new(Box::new(42));
@@ -552,8 +538,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRefMut;
+    /// use rustc_data_structures::owning_ref::OwningRefMut;
     ///
     /// fn main() {
     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
@@ -580,8 +565,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRefMut;
+    /// use rustc_data_structures::owning_ref::OwningRefMut;
     ///
     /// fn main() {
     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
@@ -608,8 +592,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRefMut;
+    /// use rustc_data_structures::owning_ref::OwningRefMut;
     ///
     /// fn main() {
     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
@@ -638,8 +621,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::OwningRefMut;
+    /// use rustc_data_structures::owning_ref::OwningRefMut;
     ///
     /// fn main() {
     ///     let owning_ref_mut = OwningRefMut::new(Box::new([1, 2, 3, 4]));
@@ -689,8 +671,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///
     /// # Example
     /// ```
-    /// extern crate owning_ref;
-    /// use owning_ref::{OwningRefMut, Erased};
+    /// use rustc_data_structures::owning_ref::{OwningRefMut, Erased};
     ///
     /// fn main() {
     ///     // N.B., using the concrete types here for explicitness.
@@ -708,7 +689,7 @@ impl<O, T: ?Sized> OwningRefMut<O, T> {
     ///     let owning_ref_mut_b: OwningRefMut<Box<Vec<(i32, bool)>>, i32>
     ///         = owning_ref_mut_b.map_mut(|a| &mut a[1].0);
     ///
-    ///     let owning_refs_mut: [OwningRefMut<Box<Erased>, i32>; 2]
+    ///     let owning_refs_mut: [OwningRefMut<Box<dyn Erased>, i32>; 2]
     ///         = [owning_ref_mut_a.erase_owner(), owning_ref_mut_b.erase_owner()];
     ///
     ///     assert_eq!(*owning_refs_mut[0], 1);
diff --git a/compiler/rustc_data_structures/src/tagged_ptr.rs b/compiler/rustc_data_structures/src/tagged_ptr.rs
index 324a8624dd0..651bc556c98 100644
--- a/compiler/rustc_data_structures/src/tagged_ptr.rs
+++ b/compiler/rustc_data_structures/src/tagged_ptr.rs
@@ -45,7 +45,8 @@ pub unsafe trait Pointer: Deref {
     /// case you'll need to manually figure out what the right type to pass to
     /// align_of is.
     ///
-    /// ```rust
+    /// ```ignore UNSOLVED (what to do about the Self)
+    /// # use std::ops::Deref;
     /// std::mem::align_of::<<Self as Deref>::Target>().trailing_zeros() as usize;
     /// ```
     const BITS: usize;
diff --git a/compiler/rustc_data_structures/src/transitive_relation.rs b/compiler/rustc_data_structures/src/transitive_relation.rs
index 780753ed200..0ff64969b07 100644
--- a/compiler/rustc_data_structures/src/transitive_relation.rs
+++ b/compiler/rustc_data_structures/src/transitive_relation.rs
@@ -282,7 +282,7 @@ impl<T: Eq + Hash + Copy> TransitiveRelation<T> {
     /// (where the relation is encoding the `<=` relation for the lattice).
     /// So e.g., if the relation is `->` and we have
     ///
-    /// ```
+    /// ```text
     /// a -> b -> d -> f
     /// |              ^
     /// +--> c -> e ---+