Improve internal docs for MatchPair

compiler/rustc_mir_build/src/build/matches/match_pair.rs

@@ -7,6 +7,11 @@ use crate::build::matches::{FlatPat, MatchPair, TestCase};
 use crate::build::Builder;
 
 impl<'a, 'tcx> Builder<'a, 'tcx> {
+    /// Builds and returns [`MatchPair`] trees, one for each pattern in
+    /// `subpatterns`, representing the fields of a [`PatKind::Variant`] or
+    /// [`PatKind::Leaf`].
+    ///
+    /// Used internally by [`MatchPair::new`].
     fn field_match_pairs<'pat>(
         &mut self,
         place: PlaceBuilder<'tcx>,
@@ -22,6 +27,10 @@ impl<'a, 'tcx> Builder<'a, 'tcx> {
             .collect()
     }
 
+    /// Builds [`MatchPair`] trees for the prefix/middle/suffix parts of an
+    /// array pattern or slice pattern, and adds those trees to `match_pairs`.
+    ///
+    /// Used internally by [`MatchPair::new`].
     fn prefix_slice_suffix<'pat>(
         &mut self,
         match_pairs: &mut Vec<MatchPair<'pat, 'tcx>>,

compiler/rustc_mir_build/src/build/matches/mod.rs

@@ -1196,17 +1196,27 @@ impl<'pat, 'tcx> TestCase<'pat, 'tcx> {
     }
 }
 
+/// Node in a tree of "match pairs", where each pair consists of a place to be
+/// tested, and a test to perform on that place.
+///
+/// Each node also has a list of subpairs (possibly empty) that must also match,
+/// and a reference to the THIR pattern it represents.
 #[derive(Debug, Clone)]
 pub(crate) struct MatchPair<'pat, 'tcx> {
     /// This place...
-    // This can be `None` if it referred to a non-captured place in a closure.
+    ///
-    // Invariant: place.is_none() => test_case is Irrefutable
+    /// ---
-    // In other words this must be `Some(_)` after simplification.
+    /// This can be `None` if it referred to a non-captured place in a closure.
+    ///
+    /// Invariant: Can only be `None` when `test_case` is `Irrefutable`.
+    /// Therefore this must be `Some(_)` after simplification.
     place: Option<Place<'tcx>>,
 
     /// ... must pass this test...
-    // Invariant: after creation and simplification in `Candidate::new()`, this must not be
+    ///
-    // `Irrefutable`.
+    /// ---
+    /// Invariant: after creation and simplification in [`FlatPat::new`],
+    /// this must not be [`TestCase::Irrefutable`].
     test_case: TestCase<'pat, 'tcx>,
 
     /// ... and these subpairs must match.