explain split better

Author: Nadrieril

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

@@ -941,13 +941,28 @@ impl ConstructorSet {
         }
     }
 
-    /// Split the set into two vecs `split` and `missing`, respecting the following:
+    /// This is the core logical operation of exhaustiveness checking.
+    /// Given a set of patterns in a match, we look at their head constructors and ask the
+    /// questions: which constructors are present in the match, and which are missing.
+    /// For this we first need to know about the full set of constructors for this type, which is
+    /// represented by this `ConstructorSet`. We then construct two lists of constructors.
+    ///
+    /// Formally, this returns two vecs `split` and `missing`, respecting the following constraints:
     /// - `split` covers the whole type
-    /// - constructors in `split` and `missing` are split for the `ctors` list
-    /// - all non-wildcards in `ctors` cover something in `split` (including `Opaques`)
-    /// - no non-wildcard in `ctors` covers anything in `missing`
-    /// - if we replace any `Wildcard`/`Missing` in `split` with all of `missing`, this also
+    /// - `split` is made of:
+    ///     - at most one wildcard (`Wildcard` or `Missing`)
+    ///     - non-wildcard constructors that are each covered by some non-wildcard constructor in `ctors`
+    ///     - together, the non-wildcard constructors in `split` cover all the non-wildcard
+    ///         constructor in `ctors`, including `Opaques`
+    /// - non-wildcards in `ctors` do no cover anything in `missing`
+    /// - if we replace the `Wildcard`/`Missing` in `split` with all of `missing`, this also
     ///     covers the whole type
+    /// - constructors in `split` and `missing` are split for the `ctors` list; in other words,
+    ///     they are either fully included in or disjoint from each constructor in `ctors`
+    ///
+    /// Note in particular that wildcards in `ctors` are irrelevant; they do not change which
+    /// constructors are present.
+    /// FIXME(Nadrieril): examples?
     pub(super) fn split<'a, 'tcx>(
         &self,
         pcx: &PatCtxt<'_, '_, 'tcx>,