Document some builtin impls in the next solver

2 files changed, 40 insertions, 0 deletions

diff --git a/compiler/rustc_target/src/abi/mod.rs b/compiler/rustc_target/src/abi/mod.rs
index 24e49ff648f..8d1c7c77bb6 100644
--- a/compiler/rustc_target/src/abi/mod.rs
+++ b/compiler/rustc_target/src/abi/mod.rs
@@ -121,6 +121,7 @@ impl<'a> Layout<'a> {
     ///
     /// Currently, that means that the type is pointer-sized, pointer-aligned,
     /// and has a initialized (non-union), scalar ABI.
+    // Please also update compiler/rustc_trait_selection/src/solve/trait_goals.rs if the criteria changes
     pub fn is_pointer_like(self, data_layout: &TargetDataLayout) -> bool {
         self.size() == data_layout.pointer_size
             && self.align().abi == data_layout.pointer_align.abi
diff --git a/compiler/rustc_trait_selection/src/solve/trait_goals.rs b/compiler/rustc_trait_selection/src/solve/trait_goals.rs
index 80198ba39f9..9c2a02a5717 100644
--- a/compiler/rustc_trait_selection/src/solve/trait_goals.rs
+++ b/compiler/rustc_trait_selection/src/solve/trait_goals.rs
@@ -188,6 +188,16 @@ impl<'tcx> assembly::GoalKind<'tcx> for TraitPredicate<'tcx> {
         })
     }
 
+    /// ```rust,ignore (not valid rust syntax)
+    /// impl Sized for u*, i*, bool, f*, FnPtr, FnDef, *(const/mut) T, char, &mut? T, [T; N], dyn* Trait, !
+    ///
+    /// impl Sized for (T1, T2, .., Tn) where T1: Sized, T2: Sized, .. Tn: Sized
+    ///
+    /// impl Sized for Adt where T: Sized forall T in field types
+    /// ```
+    ///
+    /// note that `[T; N]` is unconditionally sized since `T: Sized` is required for the array type to be
+    /// well-formed.
     fn consider_builtin_sized_candidate(
         ecx: &mut EvalCtxt<'_, 'tcx>,
         goal: Goal<'tcx, Self>,
@@ -202,6 +212,20 @@ impl<'tcx> assembly::GoalKind<'tcx> for TraitPredicate<'tcx> {
         )
     }
 
+    /// ```rust,ignore (not valid rust syntax)
+    /// impl Copy/Clone for FnDef, FnPtr
+    ///
+    /// impl Copy/Clone for (T1, T2, .., Tn) where T1: Copy/Clone, T2: Copy/Clone, .. Tn: Copy/Clone
+    ///
+    /// impl Copy/Clone for Closure where T: Copy/Clone forall T in upvars
+    ///
+    /// // only when `coroutine_clone` is enabled and the coroutine is movable
+    /// impl Copy/Clone for Coroutine where T: Copy/Clone forall T in (upvars, witnesses)
+    ///
+    /// impl Copy/Clone for CoroutineWitness where T: Copy/Clone forall T in coroutine_hidden_types
+    /// ```
+    ///
+    /// Some built-in types don't have built-in impls because they can be implemented within the standard library.
     fn consider_builtin_copy_clone_candidate(
         ecx: &mut EvalCtxt<'_, 'tcx>,
         goal: Goal<'tcx, Self>,
@@ -216,6 +240,9 @@ impl<'tcx> assembly::GoalKind<'tcx> for TraitPredicate<'tcx> {
         )
     }
 
+    /// Implements `PointerLike` for types that are pointer-sized, pointer-aligned,
+    /// and have a initialized (non-union), scalar ABI.
+    // Please also update compiler/rustc_target/src/abi/mod.rs if the criteria changes
     fn consider_builtin_pointer_like_candidate(
         ecx: &mut EvalCtxt<'_, 'tcx>,
         goal: Goal<'tcx, Self>,
@@ -245,6 +272,12 @@ impl<'tcx> assembly::GoalKind<'tcx> for TraitPredicate<'tcx> {
         }
     }
 
+    /// ```rust,ignore (not valid rust syntax)
+    /// impl FnPtr for FnPtr {}
+    /// impl !FnPtr for T where T != FnPtr && T is rigid {}
+    /// ```
+    ///
+    /// Note: see [`Ty::is_known_rigid`] for what it means for the type to be rigid.
     fn consider_builtin_fn_ptr_trait_candidate(
         ecx: &mut EvalCtxt<'_, 'tcx>,
         goal: Goal<'tcx, Self>,
@@ -375,6 +408,12 @@ impl<'tcx> assembly::GoalKind<'tcx> for TraitPredicate<'tcx> {
         }
     }
 
+    /// ```rust, ignore (not valid rust syntax)
+    /// impl Tuple for () {}
+    /// impl Tuple for (T1,) {}
+    /// impl Tuple for (T1, T2) {}
+    /// impl Tuple for (T1, .., Tn) {}
+    /// ```
     fn consider_builtin_tuple_candidate(
         ecx: &mut EvalCtxt<'_, 'tcx>,
         goal: Goal<'tcx, Self>,