Rollup merge of #78098 - camelid:fixup-docs, r=steveklabnik

Clean up and improve some docs

* compiler docs
  * Don't format list as part of a code block
  * Clean up some other formatting
* rustdoc book
  * Update CommonMark spec version to latest (0.28 -> 0.29)
  * Clean up some various wording and formatting

compiler/rustc_middle/src/middle/region.rs

@@ -292,20 +292,20 @@ pub struct ScopeTree {
     ///
     /// Then:
     ///
-    ///     1. From the ordering guarantee of HIR visitors (see
-    ///     `rustc_hir::intravisit`), `D` does not dominate `U`.
+    ///   1. From the ordering guarantee of HIR visitors (see
+    ///   `rustc_hir::intravisit`), `D` does not dominate `U`.
     ///
-    ///     2. Therefore, `D` is *potentially* storage-dead at `U` (because
-    ///     we might visit `U` without ever getting to `D`).
+    ///   2. Therefore, `D` is *potentially* storage-dead at `U` (because
+    ///   we might visit `U` without ever getting to `D`).
     ///
-    ///     3. However, we guarantee that at each HIR point, each
-    ///     binding/temporary is always either always storage-live
-    ///     or always storage-dead. This is what is being guaranteed
-    ///     by `terminating_scopes` including all blocks where the
-    ///     count of executions is not guaranteed.
+    ///   3. However, we guarantee that at each HIR point, each
+    ///   binding/temporary is always either always storage-live
+    ///   or always storage-dead. This is what is being guaranteed
+    ///   by `terminating_scopes` including all blocks where the
+    ///   count of executions is not guaranteed.
     ///
-    ///     4. By `2.` and `3.`, `D` is *statically* storage-dead at `U`,
-    ///     QED.
+    ///   4. By `2.` and `3.`, `D` is *statically* storage-dead at `U`,
+    ///   QED.
     ///
     /// This property ought to not on (3) in an essential way -- it
     /// is probably still correct even if we have "unrestricted" terminating

compiler/rustc_mir_build/src/thir/pattern/_match.rs

@@ -78,20 +78,26 @@
 //! new pattern `p`.
 //!
 //! For example, say we have the following:
+//!
 //! ```
-//!     // x: (Option<bool>, Result<()>)
-//!     match x {
-//!         (Some(true), _) => {}
-//!         (None, Err(())) => {}
-//!         (None, Err(_)) => {}
-//!     }
+//! // x: (Option<bool>, Result<()>)
+//! match x {
+//!     (Some(true), _) => {}
+//!     (None, Err(())) => {}
+//!     (None, Err(_)) => {}
+//! }
 //! ```
+//!
 //! Here, the matrix `P` starts as:
+//!
+//! ```
 //! [
 //!     [(Some(true), _)],
 //!     [(None, Err(()))],
 //!     [(None, Err(_))],
 //! ]
+//! ```
+//!
 //! We can tell it's not exhaustive, because `U(P, _)` is true (we're not covering
 //! `[(Some(false), _)]`, for instance). In addition, row 3 is not useful, because
 //! all the values it covers are already covered by row 2.
@@ -178,10 +184,14 @@
 //! This special case is handled in `is_useful_specialized`.
 //!
 //! For example, if `P` is:
+//!
+//! ```
 //! [
-//! [Some(true), _],
-//! [None, 0],
+//!     [Some(true), _],
+//!     [None, 0],
 //! ]
+//! ```
+//!
 //! and `p` is [Some(false), 0], then we don't care about row 2 since we know `p` only
 //! matches values that row 2 doesn't. For row 1 however, we need to dig into the
 //! arguments of `Some` to know whether some new value is covered. So we compute
@@ -198,10 +208,14 @@
 //! `U(P, p) := U(D(P), D(p))`
 //!
 //! For example, if `P` is:
+//!
+//! ```
 //! [
 //!     [_, true, _],
 //!     [None, false, 1],
 //! ]
+//! ```
+//!
 //! and `p` is [_, false, _], the `Some` constructor doesn't appear in `P`. So if we
 //! only had row 2, we'd know that `p` is useful. However row 1 starts with a
 //! wildcard, so we need to check whether `U([[true, _]], [false, 1])`.
@@ -215,10 +229,14 @@
 //! `U(P, p) := ∃(k ϵ constructors) U(S(k, P), S(k, p))`
 //!
 //! For example, if `P` is:
+//!
+//! ```
 //! [
 //!     [Some(true), _],
 //!     [None, false],
 //! ]
+//! ```
+//!
 //! and `p` is [_, false], both `None` and `Some` constructors appear in the first
 //! components of `P`. We will therefore try popping both constructors in turn: we
 //! compute `U([[true, _]], [_, false])` for the `Some` constructor, and `U([[false]],
@@ -1496,6 +1514,7 @@ struct PatCtxt<'tcx> {
 /// multiple patterns.
 ///
 /// For example, if we are constructing a witness for the match against
+///
 /// ```
 /// struct Pair(Option<(u32, u32)>, bool);
 ///
@@ -1619,12 +1638,14 @@ fn all_constructors<'a, 'tcx>(
             // actually match against them all themselves. So we always return only the fictitious
             // constructor.
             // E.g., in an example like:
+            //
             // ```
             //     let err: io::ErrorKind = ...;
             //     match err {
             //         io::ErrorKind::NotFound => {},
             //     }
             // ```
+            //
             // we don't want to show every possible IO error, but instead have only `_` as the
             // witness.
             let is_declared_nonexhaustive = cx.is_foreign_non_exhaustive_enum(pcx.ty);
@@ -2017,6 +2038,7 @@ crate fn is_useful<'p, 'tcx>(
         let mut unreachable_branches = Vec::new();
         // Subpatterns that are unreachable from all branches. E.g. in the following case, the last
         // `true` is unreachable only from one branch, so it is overall reachable.
+        //
         // ```
         // match (true, true) {
         //     (true, true) => {}
@@ -2161,10 +2183,12 @@ crate fn is_useful<'p, 'tcx>(
             // to do this and instead report a single `_` witness:
             // if the user didn't actually specify a constructor
             // in this arm, e.g., in
+            //
             // ```
             //     let x: (Direction, Direction, bool) = ...;
             //     let (_, _, false) = x;
             // ```
+            //
             // we don't want to show all 16 possible witnesses
             // `(<direction-1>, <direction-2>, true)` - we are
             // satisfied with `(_, _, true)`. In this case,

src/doc/rustdoc/src/documentation-tests.md

@@ -16,8 +16,8 @@ The basic idea is this:
 The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
 running `rustdoc --test foo.rs` will extract this example, and then run it as a test.
 
-Please note that by default, if no language is set for the block code, `rustdoc`
-assumes it is `Rust` code. So the following:
+Please note that by default, if no language is set for the block code, rustdoc
+assumes it is Rust code. So the following:
 
 ``````markdown
 ```rust
@@ -44,7 +44,6 @@ the `assert!` family of macros works the same as other Rust code:
 
 ```rust
 let foo = "foo";
-
 assert_eq!(foo, "foo");
 ```
 
@@ -55,8 +54,9 @@ the code panics and the doctest fails.
 
 In the example above, you'll note something strange: there's no `main`
 function! Forcing you to write `main` for every example, no matter how small,
-adds friction. So `rustdoc` processes your examples slightly before
-running them. Here's the full algorithm rustdoc uses to preprocess examples:
+adds friction and clutters the output. So `rustdoc` processes your examples
+slightly before running them. Here's the full algorithm `rustdoc` uses to
+preprocess examples:
 
 1. Some common `allow` attributes are inserted, including
    `unused_variables`, `unused_assignments`, `unused_mut`,
@@ -78,10 +78,12 @@ Sometimes, you need some setup code, or other things that would distract
 from your example, but are important to make the tests work. Consider
 an example block that looks like this:
 
-```text
+```ignore
+/// ```
 /// /// Some documentation.
 /// # fn foo() {} // this function will be hidden
 /// println!("Hello, World!");
+/// ```
 ```
 
 It will render like this:
@@ -251,7 +253,7 @@ disambiguate the error type:
 This is an unfortunate consequence of the `?` operator adding an implicit
 conversion, so type inference fails because the type is not unique. Please note
 that you must write the `(())` in one sequence without intermediate whitespace
-so that rustdoc understands you want an implicit `Result`-returning function.
+so that `rustdoc` understands you want an implicit `Result`-returning function.
 
 ## Documenting macros
 
@@ -359,7 +361,7 @@ the code with the 2015 edition.
 ## Syntax reference
 
 The *exact* syntax for code blocks, including the edge cases, can be found
-in the [Fenced Code Blocks](https://spec.commonmark.org/0.28/#fenced-code-blocks)
+in the [Fenced Code Blocks](https://spec.commonmark.org/0.29/#fenced-code-blocks)
 section of the CommonMark specification.
 
 Rustdoc also accepts *indented* code blocks as an alternative to fenced
@@ -372,7 +374,7 @@ can indent each line by four or more spaces.
 ``````
 
 These, too, are documented in the CommonMark specification, in the
-[Indented Code Blocks](https://spec.commonmark.org/0.28/#indented-code-blocks)
+[Indented Code Blocks](https://spec.commonmark.org/0.29/#indented-code-blocks)
 section.
 
 However, it's preferable to use fenced code blocks over indented code blocks.
@@ -388,7 +390,7 @@ documentation. To this end, Rustdoc allows you to have certain items only appear
 collecting doctests, so you can utilize doctest functionality without forcing the test to appear in
 docs, or to find an arbitrary private item to include it on.
 
-When compiling a crate for use in doctests (with `--test` option), rustdoc will set `cfg(doctest)`.
+When compiling a crate for use in doctests (with `--test` option), `rustdoc` will set `#[cfg(doctest)]`.
 Note that they will still link against only the public items of your crate; if you need to test
 private items, you need to write a unit test.
 
@@ -407,18 +409,18 @@ pub struct MyStructOnlyTakesUsize;
 ```
 
 Note that the struct `MyStructOnlyTakesUsize` here isn't actually part of your public crate
-API. The use of `#[cfg(doctest)]` makes sure that this struct only exists while rustdoc is
+API. The use of `#[cfg(doctest)]` makes sure that this struct only exists while `rustdoc` is
 collecting doctests. This means that its doctest is executed when `--test` is passed to rustdoc,
 but is hidden from the public documentation.
 
-Another possible use of `cfg(doctest)` is to test doctests that are included in your README file
+Another possible use of `#[cfg(doctest)]` is to test doctests that are included in your README file
 without including it in your main documentation. For example, you could write this into your
 `lib.rs` to test your README as part of your doctests:
 
 ```rust,ignore
 #![feature(external_doc)]
 
-#[doc(include="../README.md")]
+#[doc(include = "../README.md")]
 #[cfg(doctest)]
 pub struct ReadmeDoctests;
 ```