From 3be52b594114bcc813e0d7c901f719526fb0b601 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 1 May 2020 22:28:15 +0200 Subject: [PATCH] fix rustdoc warnings --- .../deriving/generic/ty.rs | 2 +- src/librustc_builtin_macros/test_harness.rs | 2 ++ src/librustc_codegen_llvm/context.rs | 7 ++++--- src/librustc_codegen_ssa/traits/declare.rs | 2 +- .../obligation_forest/mod.rs | 2 +- .../transitive_relation.rs | 2 +- src/librustc_hir/arena.rs | 4 ++-- .../infer/error_reporting/mod.rs | 2 +- src/librustc_infer/infer/mod.rs | 2 +- .../infer/region_constraints/mod.rs | 2 +- src/librustc_lint/levels.rs | 4 ++-- src/librustc_middle/arena.rs | 2 +- src/librustc_middle/mir/mod.rs | 6 +++--- src/librustc_middle/mir/query.rs | 2 +- src/librustc_middle/ty/layout.rs | 4 ++-- src/librustc_middle/ty/mod.rs | 2 +- .../diagnostics/conflict_errors.rs | 6 ++++-- .../transform/cleanup_post_borrowck.rs | 6 ++++-- src/librustc_mir_build/hair/pattern/_match.rs | 2 ++ src/librustc_resolve/diagnostics.rs | 4 ++-- src/librustc_resolve/lib.rs | 2 +- src/librustc_span/hygiene.rs | 2 +- .../traits/coherence.rs | 4 ++-- src/librustc_ty/ty.rs | 2 +- src/librustc_typeck/check/regionck.rs | 18 ++++++++++-------- src/librustc_typeck/mem_categorization.rs | 2 +- src/librustdoc/html/toc.rs | 6 +++--- 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 d83c98572a272..23980a2db8d42 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>, 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 160a5204eaf70..fa5993471c44a 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 f868385ee869a..36f1ece40d6b5 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>, /// 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>, diff --git a/src/librustc_codegen_ssa/traits/declare.rs b/src/librustc_codegen_ssa/traits/declare.rs index de63ef7961387..690aacd20566b 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; /// 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 6711a49b2b7c1..197169b7036e0 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 { /// must all be in a non-pending state. dependents: Vec, - /// 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` 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 16f2e740104ca..de503fe8228aa 100644 --- a/src/librustc_data_structures/transitive_relation.rs +++ b/src/librustc_data_structures/transitive_relation.rs @@ -289,7 +289,7 @@ impl TransitiveRelation { /// /// - 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 b8a691dd9813e..a0b19f61906ed 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 9de7dcc845f1d..50e97c8fb7a02 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> = foo::>(); /// ``` /// diff --git a/src/librustc_infer/infer/mod.rs b/src/librustc_infer/infer/mod.rs index 267f1e7e2dc89..54f80e8f38812 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 1292e96ff98e7..2be6ec4481c6b 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 { self.undo_log[mark.length..] .iter() diff --git a/src/librustc_lint/levels.rs b/src/librustc_lint/levels.rs index 7e8e4f59707c1..12f4cd33689e6 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 bbeacbfc5382e..96ef4b3741200 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 4d7104531753c..8d416536155ac 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>, - /// 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 95a28df99aad0..63b8d8c8da782 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 6b7672a57f055..4cdcd5320e761 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 bef74289fd850..7064b24240ef6 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 7492654583025..5bc9f6df889c7 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 a3880d691b2d1..e80da4f756c64 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 51ba84416d64d..de3ae2e961f42 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 88ec4585b0059..450293b991bde 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 d84edbe3ad77b..d33eaf5a827db 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 0afa2333e0615..23c3dccb130f6 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>, diff --git a/src/librustc_trait_selection/traits/coherence.rs b/src/librustc_trait_selection/traits/coherence.rs index f1311382c5447..f9ff772900bbd 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 b65f1cd6fac4e..c5ead053a7f89 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> { debug!("issue33140_self_ty({:?})", def_id); diff --git a/src/librustc_typeck/check/regionck.rs b/src/librustc_typeck/check/regionck.rs index 53d6ec96bd251..049f4767247c5 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 f6edb6b754534..ffe9f1c7d7a71 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 3754029577475..721988e29a678 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).