Rollup merge of #71787 - tshepang:rustdoc-warnings, r=varkor

fix rustdoc warnings

27 files changed, 56 insertions, 45 deletions

diff --git a/src/librustc_builtin_macros/deriving/generic/ty.rs b/src/librustc_builtin_macros/deriving/generic/ty.rs
index d83c98572a2..23980a2db8d 100644
--- a/src/librustc_builtin_macros/deriving/generic/ty.rs
+++ b/src/librustc_builtin_macros/deriving/generic/ty.rs
@@ -98,7 +98,7 @@ pub enum Ty<'a> {
     Self_,
     /// &/Box/ Ty
     Ptr(Box<Ty<'a>>, PtrTy),
-    /// mod::mod::Type<[lifetime], [Params...]>, including a plain type
+    /// `mod::mod::Type<[lifetime], [Params...]>`, including a plain type
     /// parameter, and things like `i32`
     Literal(Path<'a>),
     /// includes unit
diff --git a/src/librustc_builtin_macros/test_harness.rs b/src/librustc_builtin_macros/test_harness.rs
index 160a5204eaf..fa5993471c4 100644
--- a/src/librustc_builtin_macros/test_harness.rs
+++ b/src/librustc_builtin_macros/test_harness.rs
@@ -233,6 +233,7 @@ fn generate_test_harness(
 ///
 /// By default this expands to
 ///
+/// ```
 /// #[main]
 /// pub fn main() {
 ///     extern crate test;
@@ -242,6 +243,7 @@ fn generate_test_harness(
 ///         &test_const3,
 ///     ]);
 /// }
+/// ```
 ///
 /// Most of the Ident have the usual def-site hygiene for the AST pass. The
 /// exception is the `test_const`s. These have a syntax context that has two
diff --git a/src/librustc_codegen_llvm/context.rs b/src/librustc_codegen_llvm/context.rs
index b33aba0ef8f..01f90cae7a5 100644
--- a/src/librustc_codegen_llvm/context.rs
+++ b/src/librustc_codegen_llvm/context.rs
@@ -49,12 +49,13 @@ pub struct CodegenCx<'ll, 'tcx> {
     pub const_cstr_cache: RefCell<FxHashMap<Symbol, &'ll Value>>,
 
     /// Reverse-direction for const ptrs cast from globals.
-    /// Key is a Value holding a *T,
-    /// Val is a Value holding a *[T].
+    ///
+    /// Key is a Value holding a `*T`,
+    /// Val is a Value holding a `*[T]`.
     ///
     /// Needed because LLVM loses pointer->pointee association
     /// when we ptrcast, and we have to ptrcast during codegen
-    /// of a [T] const because we form a slice, a (*T,usize) pair, not
+    /// of a `[T]` const because we form a slice, a `(*T,usize)` pair, not
     /// a pointer to an LLVM array type. Similar for trait objects.
     pub const_unsized: RefCell<FxHashMap<&'ll Value, &'ll Value>>,
 
diff --git a/src/librustc_codegen_ssa/traits/declare.rs b/src/librustc_codegen_ssa/traits/declare.rs
index de63ef79613..690aacd2056 100644
--- a/src/librustc_codegen_ssa/traits/declare.rs
+++ b/src/librustc_codegen_ssa/traits/declare.rs
@@ -31,7 +31,7 @@ pub trait DeclareMethods<'tcx>: BackendTypes {
     /// Use this function when you intend to define a global. This function will
     /// return `None` if the name already has a definition associated with it. In that
     /// case an error should be reported to the user, because it usually happens due
-    /// to user’s fault (e.g., misuse of #[no_mangle] or #[export_name] attributes).
+    /// to user’s fault (e.g., misuse of `#[no_mangle]` or `#[export_name]` attributes).
     fn define_global(&self, name: &str, ty: Self::Type) -> Option<Self::Value>;
 
     /// Declare a private global
diff --git a/src/librustc_data_structures/obligation_forest/mod.rs b/src/librustc_data_structures/obligation_forest/mod.rs
index 6711a49b2b7..197169b7036 100644
--- a/src/librustc_data_structures/obligation_forest/mod.rs
+++ b/src/librustc_data_structures/obligation_forest/mod.rs
@@ -173,7 +173,7 @@ struct Node<O> {
     /// must all be in a non-pending state.
     dependents: Vec<usize>,
 
-    /// If true, dependents[0] points to a "parent" node, which requires
+    /// If true, `dependents[0]` points to a "parent" node, which requires
     /// special treatment upon error but is otherwise treated the same.
     /// (It would be more idiomatic to store the parent node in a separate
     /// `Option<usize>` field, but that slows down the common case of
diff --git a/src/librustc_data_structures/transitive_relation.rs b/src/librustc_data_structures/transitive_relation.rs
index 16f2e740104..de503fe8228 100644
--- a/src/librustc_data_structures/transitive_relation.rs
+++ b/src/librustc_data_structures/transitive_relation.rs
@@ -289,7 +289,7 @@ impl<T: Clone + Debug + Eq + Hash> TransitiveRelation<T> {
     ///
     /// - A != B
     /// - A R B is true
-    /// - for each i, j: B[i] R B[j] does not hold
+    /// - for each i, j: `B[i]` R `B[j]` does not hold
     ///
     /// The intuition is that this moves "one step up" through a lattice
     /// (where the relation is encoding the `<=` relation for the lattice).
diff --git a/src/librustc_hir/arena.rs b/src/librustc_hir/arena.rs
index b8a691dd981..a0b19f61906 100644
--- a/src/librustc_hir/arena.rs
+++ b/src/librustc_hir/arena.rs
@@ -5,8 +5,8 @@
 /// Leaving `few` out will cause the type to get its own dedicated `TypedArena` which is
 /// faster and more memory efficient if there is lots of allocations.
 ///
-/// Specifying the `decode` modifier will add decode impls for &T and &[T] where T is the type
-/// listed. These impls will appear in the implement_ty_decoder! macro.
+/// Specifying the `decode` modifier will add decode impls for `&T` and `&[T]`,
+/// where `T` is the type listed. These impls will appear in the implement_ty_decoder! macro.
 #[macro_export]
 macro_rules! arena_types {
     ($macro:path, $args:tt, $tcx:lifetime) => (
diff --git a/src/librustc_infer/infer/error_reporting/mod.rs b/src/librustc_infer/infer/error_reporting/mod.rs
index 9de7dcc845f..50e97c8fb7a 100644
--- a/src/librustc_infer/infer/error_reporting/mod.rs
+++ b/src/librustc_infer/infer/error_reporting/mod.rs
@@ -843,7 +843,7 @@ impl<'a, 'tcx> InferCtxt<'a, 'tcx> {
     ///
     /// For the following code:
     ///
-    /// ```norun
+    /// ```no_run
     /// let x: Foo<Bar<Qux>> = foo::<Bar<Qux>>();
     /// ```
     ///
diff --git a/src/librustc_infer/infer/mod.rs b/src/librustc_infer/infer/mod.rs
index 267f1e7e2dc..54f80e8f388 100644
--- a/src/librustc_infer/infer/mod.rs
+++ b/src/librustc_infer/infer/mod.rs
@@ -1482,7 +1482,7 @@ impl<'a, 'tcx> InferCtxt<'a, 'tcx> {
         self.tcx.replace_bound_vars(value, fld_r, fld_t, fld_c)
     }
 
-    /// See the [`region_constraints::verify_generic_bound`] method.
+    /// See the [`region_constraints::RegionConstraintCollector::verify_generic_bound`] method.
     pub fn verify_generic_bound(
         &self,
         origin: SubregionOrigin<'tcx>,
diff --git a/src/librustc_infer/infer/region_constraints/mod.rs b/src/librustc_infer/infer/region_constraints/mod.rs
index 1292e96ff98..2be6ec4481c 100644
--- a/src/librustc_infer/infer/region_constraints/mod.rs
+++ b/src/librustc_infer/infer/region_constraints/mod.rs
@@ -810,7 +810,7 @@ impl<'tcx> RegionConstraintCollector<'tcx> {
         )
     }
 
-    /// See [`RegionInference::region_constraints_added_in_snapshot`].
+    /// See `InferCtxt::region_constraints_added_in_snapshot`.
     pub fn region_constraints_added_in_snapshot(&self, mark: &RegionSnapshot) -> Option<bool> {
         self.undo_log[mark.length..]
             .iter()
diff --git a/src/librustc_lint/levels.rs b/src/librustc_lint/levels.rs
index 7e8e4f59707..12f4cd33689 100644
--- a/src/librustc_lint/levels.rs
+++ b/src/librustc_lint/levels.rs
@@ -103,8 +103,8 @@ impl<'s> LintLevelsBuilder<'s> {
     /// * It'll validate all lint-related attributes in `attrs`
     /// * It'll mark all lint-related attributes as used
     /// * Lint levels will be updated based on the attributes provided
-    /// * Lint attributes are validated, e.g., a #[forbid] can't be switched to
-    ///   #[allow]
+    /// * Lint attributes are validated, e.g., a `#[forbid]` can't be switched to
+    ///   `#[allow]`
     ///
     /// Don't forget to call `pop`!
     pub fn push(&mut self, attrs: &[ast::Attribute], store: &LintStore) -> BuilderPush {
diff --git a/src/librustc_middle/arena.rs b/src/librustc_middle/arena.rs
index bbeacbfc538..96ef4b37412 100644
--- a/src/librustc_middle/arena.rs
+++ b/src/librustc_middle/arena.rs
@@ -5,7 +5,7 @@
 /// Leaving `few` out will cause the type to get its own dedicated `TypedArena` which is
 /// faster and more memory efficient if there is lots of allocations.
 ///
-/// Specifying the `decode` modifier will add decode impls for &T and &[T] where T is the type
+/// Specifying the `decode` modifier will add decode impls for `&T` and `&[T]` where `T` is the type
 /// listed. These impls will appear in the implement_ty_decoder! macro.
 #[macro_export]
 macro_rules! arena_types {
diff --git a/src/librustc_middle/mir/mod.rs b/src/librustc_middle/mir/mod.rs
index 4d710453175..8d416536155 100644
--- a/src/librustc_middle/mir/mod.rs
+++ b/src/librustc_middle/mir/mod.rs
@@ -158,10 +158,10 @@ pub struct Body<'tcx> {
     /// We hold in this field all the constants we are not able to evaluate yet.
     pub required_consts: Vec<Constant<'tcx>>,
 
-    /// The user may be writing e.g. &[(SOME_CELL, 42)][i].1 and this would get promoted, because
+    /// The user may be writing e.g. `&[(SOME_CELL, 42)][i].1` and this would get promoted, because
     /// we'd statically know that no thing with interior mutability will ever be available to the
     /// user without some serious unsafe code.  Now this means that our promoted is actually
-    /// &[(SOME_CELL, 42)] and the MIR using it will do the &promoted[i].1 projection because the
+    /// `&[(SOME_CELL, 42)]` and the MIR using it will do the `&promoted[i].1` projection because the
     /// index may be a runtime value. Such a promoted value is illegal because it has reachable
     /// interior mutability. This flag just makes this situation very obvious where the previous
     /// implementation without the flag hid this situation silently.
@@ -2124,7 +2124,7 @@ pub enum Rvalue<'tcx> {
     /// or when casting a reference to a raw pointer.
     AddressOf(Mutability, Place<'tcx>),
 
-    /// length of a [X] or [X;n] value
+    /// length of a `[X]` or `[X;n]` value
     Len(Place<'tcx>),
 
     Cast(CastKind, Operand<'tcx>, Ty<'tcx>),
diff --git a/src/librustc_middle/mir/query.rs b/src/librustc_middle/mir/query.rs
index 95a28df99aa..63b8d8c8da7 100644
--- a/src/librustc_middle/mir/query.rs
+++ b/src/librustc_middle/mir/query.rs
@@ -167,7 +167,7 @@ pub struct ClosureOutlivesRequirement<'tcx> {
 /// are interesting (for error reporting). Order of variants indicates sort
 /// order of the category, thereby influencing diagnostic output.
 ///
-/// See also [rustc_mir::borrow_check::nll::constraints].
+/// See also `rustc_mir::borrow_check::constraints`.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
 #[derive(RustcEncodable, RustcDecodable, HashStable)]
 pub enum ConstraintCategory {
diff --git a/src/librustc_middle/ty/layout.rs b/src/librustc_middle/ty/layout.rs
index 6b7672a57f0..4cdcd5320e7 100644
--- a/src/librustc_middle/ty/layout.rs
+++ b/src/librustc_middle/ty/layout.rs
@@ -70,8 +70,8 @@ impl IntegerExt for Integer {
     }
 
     /// Finds the appropriate Integer type and signedness for the given
-    /// signed discriminant range and #[repr] attribute.
-    /// N.B.: u128 values above i128::MAX will be treated as signed, but
+    /// signed discriminant range and `#[repr]` attribute.
+    /// N.B.: `u128` values above `i128::MAX` will be treated as signed, but
     /// that shouldn't affect anything, other than maybe debuginfo.
     fn repr_discr<'tcx>(
         tcx: TyCtxt<'tcx>,
diff --git a/src/librustc_middle/ty/mod.rs b/src/librustc_middle/ty/mod.rs
index bef74289fd8..7064b24240e 100644
--- a/src/librustc_middle/ty/mod.rs
+++ b/src/librustc_middle/ty/mod.rs
@@ -2696,7 +2696,7 @@ impl<'tcx> TyCtxt<'tcx> {
     }
 
     /// Returns `true` if the impls are the same polarity and the trait either
-    /// has no items or is annotated #[marker] and prevents item overrides.
+    /// has no items or is annotated `#[marker]` and prevents item overrides.
     pub fn impls_are_allowed_to_overlap(
         self,
         def_id1: DefId,
diff --git a/src/librustc_mir/borrow_check/diagnostics/conflict_errors.rs b/src/librustc_mir/borrow_check/diagnostics/conflict_errors.rs
index 74926545830..5bc9f6df889 100644
--- a/src/librustc_mir/borrow_check/diagnostics/conflict_errors.rs
+++ b/src/librustc_mir/borrow_check/diagnostics/conflict_errors.rs
@@ -582,8 +582,10 @@ impl<'cx, 'tcx> MirBorrowckCtxt<'cx, 'tcx> {
     ///
     /// This is used when creating error messages like below:
     ///
-    /// >  cannot borrow `a.u` (via `a.u.z.c`) as immutable because it is also borrowed as
-    /// >  mutable (via `a.u.s.b`) [E0502]
+    /// ```text
+    /// cannot borrow `a.u` (via `a.u.z.c`) as immutable because it is also borrowed as
+    /// mutable (via `a.u.s.b`) [E0502]
+    /// ```
     pub(in crate::borrow_check) fn describe_place_for_conflicting_borrow(
         &self,
         first_borrowed_place: Place<'tcx>,
diff --git a/src/librustc_mir/transform/cleanup_post_borrowck.rs b/src/librustc_mir/transform/cleanup_post_borrowck.rs
index a3880d691b2..e80da4f756c 100644
--- a/src/librustc_mir/transform/cleanup_post_borrowck.rs
+++ b/src/librustc_mir/transform/cleanup_post_borrowck.rs
@@ -7,13 +7,15 @@
 //!
 //! The `CleanFakeReadsAndBorrows` "pass" is actually implemented as two
 //! traversals (aka visits) of the input MIR. The first traversal,
-//! [`DeleteAndRecordFakeReads`], deletes the fake reads and finds the
-//! temporaries read by [`ForMatchGuard`] reads, and [`DeleteFakeBorrows`]
+//! `DeleteAndRecordFakeReads`, deletes the fake reads and finds the
+//! temporaries read by [`ForMatchGuard`] reads, and `DeleteFakeBorrows`
 //! deletes the initialization of those temporaries.
 //!
 //! [`AscribeUserType`]: rustc_middle::mir::StatementKind::AscribeUserType
 //! [`Shallow`]: rustc_middle::mir::BorrowKind::Shallow
 //! [`FakeRead`]: rustc_middle::mir::StatementKind::FakeRead
+//! [`Assign`]: rustc_middle::mir::StatementKind::Assign
+//! [`ForMatchGuard`]: rustc_middle::mir::FakeReadCause::ForMatchGuard
 //! [`Nop`]: rustc_middle::mir::StatementKind::Nop
 
 use crate::transform::{MirPass, MirSource};
diff --git a/src/librustc_mir_build/hair/pattern/_match.rs b/src/librustc_mir_build/hair/pattern/_match.rs
index 51ba84416d6..de3ae2e961f 100644
--- a/src/librustc_mir_build/hair/pattern/_match.rs
+++ b/src/librustc_mir_build/hair/pattern/_match.rs
@@ -513,6 +513,8 @@ impl<'p, 'tcx> Matrix<'p, 'tcx> {
 }
 
 /// Pretty-printer for matrices of patterns, example:
+///
+/// ```text
 /// +++++++++++++++++++++++++++++
 /// + _     + []                +
 /// +++++++++++++++++++++++++++++
diff --git a/src/librustc_resolve/diagnostics.rs b/src/librustc_resolve/diagnostics.rs
index 88ec4585b00..450293b991b 100644
--- a/src/librustc_resolve/diagnostics.rs
+++ b/src/librustc_resolve/diagnostics.rs
@@ -1051,7 +1051,7 @@ impl<'a, 'b> ImportResolver<'a, 'b> {
 
     /// Suggests a missing `crate::` if that resolves to an correct module.
     ///
-    /// ```
+    /// ```text
     ///    |
     /// LL | use foo::Bar;
     ///    |     ^^^ did you mean `crate::foo`?
@@ -1147,7 +1147,7 @@ impl<'a, 'b> ImportResolver<'a, 'b> {
     /// Suggests importing a macro from the root of the crate rather than a module within
     /// the crate.
     ///
-    /// ```
+    /// ```text
     /// help: a macro with this name exists at the root of the crate
     ///    |
     /// LL | use issue_59764::makro;
diff --git a/src/librustc_resolve/lib.rs b/src/librustc_resolve/lib.rs
index d84edbe3ad7..d33eaf5a827 100644
--- a/src/librustc_resolve/lib.rs
+++ b/src/librustc_resolve/lib.rs
@@ -2669,7 +2669,7 @@ impl<'a> Resolver<'a> {
     /// This function adds a suggestion to change the binding name of a new import that conflicts
     /// with an existing import.
     ///
-    /// ```ignore (diagnostic)
+    /// ```text,ignore (diagnostic)
     /// help: you can use `as` to change the binding name of the import
     ///    |
     /// LL | use foo::bar as other_bar;
diff --git a/src/librustc_span/hygiene.rs b/src/librustc_span/hygiene.rs
index 0afa2333e06..23c3dccb130 100644
--- a/src/librustc_span/hygiene.rs
+++ b/src/librustc_span/hygiene.rs
@@ -661,7 +661,7 @@ pub struct ExpnData {
     /// The span of the macro definition (possibly dummy).
     /// This span serves only informational purpose and is not used for resolution.
     pub def_site: Span,
-    /// List of #[unstable]/feature-gated features that the macro is allowed to use
+    /// List of `#[unstable]`/feature-gated features that the macro is allowed to use
     /// internally without forcing the whole crate to opt-in
     /// to them.
     pub allow_internal_unstable: Option<Lrc<[Symbol]>>,
diff --git a/src/librustc_trait_selection/traits/coherence.rs b/src/librustc_trait_selection/traits/coherence.rs
index f1311382c54..f9ff772900b 100644
--- a/src/librustc_trait_selection/traits/coherence.rs
+++ b/src/librustc_trait_selection/traits/coherence.rs
@@ -327,12 +327,12 @@ pub fn orphan_check(tcx: TyCtxt<'_>, impl_def_id: DefId) -> Result<(), OrphanChe
 ///    try to implement this trait-ref. To check for this, we use InCrate::Remote
 ///    mode. That is sound because we already know all the impls from known crates.
 ///
-/// 3. For non-#[fundamental] traits, they guarantee that parent crates can
+/// 3. For non-`#[fundamental]` traits, they guarantee that parent crates can
 ///    add "non-blanket" impls without breaking negative reasoning in dependent
 ///    crates. This is the "rebalancing coherence" (RFC 1023) restriction.
 ///
 ///    For that, we only a allow crate to perform negative reasoning on
-///    non-local-non-#[fundamental] only if there's a local key parameter as per (2).
+///    non-local-non-`#[fundamental]` only if there's a local key parameter as per (2).
 ///
 ///    Because we never perform negative reasoning generically (coherence does
 ///    not involve type parameters), this can be interpreted as doing the full
diff --git a/src/librustc_ty/ty.rs b/src/librustc_ty/ty.rs
index b65f1cd6fac..c5ead053a7f 100644
--- a/src/librustc_ty/ty.rs
+++ b/src/librustc_ty/ty.rs
@@ -307,7 +307,7 @@ fn instance_def_size_estimate<'tcx>(
 
 /// If `def_id` is an issue 33140 hack impl, returns its self type; otherwise, returns `None`.
 ///
-/// See [`ImplOverlapKind::Issue33140`] for more details.
+/// See [`ty::ImplOverlapKind::Issue33140`] for more details.
 fn issue33140_self_ty(tcx: TyCtxt<'_>, def_id: DefId) -> Option<Ty<'_>> {
     debug!("issue33140_self_ty({:?})", def_id);
 
diff --git a/src/librustc_typeck/check/regionck.rs b/src/librustc_typeck/check/regionck.rs
index 53d6ec96bd2..049f4767247 100644
--- a/src/librustc_typeck/check/regionck.rs
+++ b/src/librustc_typeck/check/regionck.rs
@@ -1105,19 +1105,21 @@ impl<'a, 'tcx> RegionCtxt<'a, 'tcx> {
     /// itself the referent of a borrowed pointer. Let me give an
     /// example fragment of code to make clear(er) the situation:
     ///
-    ///    let r: &'a mut T = ...;  // the original reference "r" has lifetime 'a
-    ///    ...
-    ///    &'z *r                   // the reborrow has lifetime 'z
+    /// ```ignore (incomplete Rust code)
+    /// let r: &'a mut T = ...;  // the original reference "r" has lifetime 'a
+    /// ...
+    /// &'z *r                   // the reborrow has lifetime 'z
+    /// ```
     ///
     /// Now, in this case, our primary job is to add the inference
     /// constraint that `'z <= 'a`. Given this setup, let's clarify the
     /// parameters in (roughly) terms of the example:
     ///
     /// ```plain,ignore (pseudo-Rust)
-    ///     A borrow of: `& 'z bk * r` where `r` has type `& 'a bk T`
-    ///     borrow_region   ^~                 ref_region    ^~
-    ///     borrow_kind        ^~               ref_kind        ^~
-    ///     ref_cmt                 ^
+    /// A borrow of: `& 'z bk * r` where `r` has type `& 'a bk T`
+    /// borrow_region   ^~                 ref_region    ^~
+    /// borrow_kind        ^~               ref_kind        ^~
+    /// ref_cmt                 ^
     /// ```
     ///
     /// Here `bk` stands for some borrow-kind (e.g., `mut`, `uniq`, etc).
@@ -1193,7 +1195,7 @@ impl<'a, 'tcx> RegionCtxt<'a, 'tcx> {
     ///   a `FnMut` or `Fn` closure.
     ///
     /// This function links the lifetimes of those references to the lifetime
-    /// of the borrow that's provided. See [link_reborrowed_region] for some
+    /// of the borrow that's provided. See [RegionCtxt::link_reborrowed_region] for some
     /// more explanation of this in the general case.
     ///
     /// We also supply a *cause*, and in this case we set the cause to
diff --git a/src/librustc_typeck/mem_categorization.rs b/src/librustc_typeck/mem_categorization.rs
index f6edb6b7545..ffe9f1c7d7a 100644
--- a/src/librustc_typeck/mem_categorization.rs
+++ b/src/librustc_typeck/mem_categorization.rs
@@ -30,7 +30,7 @@
 //! - `ty`: the type of data found at the address `A`.
 //!
 //! The resulting categorization tree differs somewhat from the expressions
-//! themselves. For example, auto-derefs are explicit. Also, an index a[b] is
+//! themselves. For example, auto-derefs are explicit. Also, an index `a[b]` is
 //! decomposed into two operations: a dereference to reach the array data and
 //! then an index to jump forward to the relevant item.
 //!
diff --git a/src/librustdoc/html/toc.rs b/src/librustdoc/html/toc.rs
index 37540295774..721988e29a6 100644
--- a/src/librustdoc/html/toc.rs
+++ b/src/librustdoc/html/toc.rs
@@ -5,7 +5,7 @@
 pub struct Toc {
     /// The levels are strictly decreasing, i.e.
     ///
-    /// entries[0].level >= entries[1].level >= ...
+    /// `entries[0].level >= entries[1].level >= ...`
     ///
     /// Normally they are equal, but can differ in cases like A and B,
     /// both of which end up in the same `Toc` as they have the same
@@ -39,8 +39,8 @@ pub struct TocEntry {
 pub struct TocBuilder {
     top_level: Toc,
     /// The current hierarchy of parent headings, the levels are
-    /// strictly increasing (i.e., chain[0].level < chain[1].level <
-    /// ...) with each entry being the most recent occurrence of a
+    /// strictly increasing (i.e., `chain[0].level < chain[1].level <
+    /// ...`) with each entry being the most recent occurrence of a
     /// heading with that level (it doesn't include the most recent
     /// occurrences of every level, just, if it *is* in `chain` then
     /// it is the most recent one).