From c88ba28d9a0261f448471255bd913e673858abaa Mon Sep 17 00:00:00 2001
From: mejrs <59372212+mejrs@users.noreply.github.com>
Date: Mon, 4 Nov 2024 18:08:30 +0100
Subject: [PATCH 1/2] document `type_implements_trait`

---
 compiler/rustc_trait_selection/src/infer.rs | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/compiler/rustc_trait_selection/src/infer.rs b/compiler/rustc_trait_selection/src/infer.rs
index bacb3b1b1b8..e91574fa1af 100644
--- a/compiler/rustc_trait_selection/src/infer.rs
+++ b/compiler/rustc_trait_selection/src/infer.rs
@@ -60,6 +60,18 @@ fn type_is_sized_modulo_regions(&self, param_env: ty::ParamEnv<'tcx>, ty: Ty<'tc
     ///
     /// Invokes `evaluate_obligation`, so in the event that evaluating
     /// `Ty: Trait` causes overflow, EvaluatedToAmbigStackDependent will be returned.
+    ///
+    /// `type_implements_trait` is a convenience function for simple cases like
+    ///
+    /// ```ignore (illustrative)
+    /// let copy_trait = infcx.tcx.require_lang_item(LangItem::Copy, span);
+    /// let implements_copy = infcx.type_implements_trait(copy_trait, [ty], param_env)
+    /// .must_apply_modulo_regions();
+    /// ```
+    ///
+    /// In most cases you should instead create an [Obligation](traits::Obligation)
+    /// and check whether it holds, because it properly handles higher ranked traits
+    /// and it is more convenient and safer when your `params` are inside a `Binder`.
     #[instrument(level = "debug", skip(self, params), ret)]
     fn type_implements_trait(
         &self,

From e37a3a85e44f2c43442acf41e5d9d704738ee84c Mon Sep 17 00:00:00 2001
From: mejrs <59372212+mejrs@users.noreply.github.com>
Date: Tue, 5 Nov 2024 01:08:20 +0100
Subject: [PATCH 2/2] Explain how to evaluate an obligation

---
 compiler/rustc_trait_selection/src/infer.rs | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/compiler/rustc_trait_selection/src/infer.rs b/compiler/rustc_trait_selection/src/infer.rs
index e91574fa1af..8f1c8a29663 100644
--- a/compiler/rustc_trait_selection/src/infer.rs
+++ b/compiler/rustc_trait_selection/src/infer.rs
@@ -69,9 +69,15 @@ fn type_is_sized_modulo_regions(&self, param_env: ty::ParamEnv<'tcx>, ty: Ty<'tc
     /// .must_apply_modulo_regions();
     /// ```
     ///
-    /// In most cases you should instead create an [Obligation](traits::Obligation)
-    /// and check whether it holds, because it properly handles higher ranked traits
-    /// and it is more convenient and safer when your `params` are inside a `Binder`.
+    /// In most cases you should instead create an [Obligation] and check whether
+    ///  it holds via [`evaluate_obligation`] or one of its helper functions like
+    /// [`predicate_must_hold_modulo_regions`], because it properly handles higher ranked traits
+    /// and it is more convenient and safer when your `params` are inside a [`Binder`].
+    ///
+    /// [Obligation]: traits::Obligation
+    /// [`evaluate_obligation`]: crate::traits::query::evaluate_obligation::InferCtxtExt::evaluate_obligation
+    /// [`predicate_must_hold_modulo_regions`]: crate::traits::query::evaluate_obligation::InferCtxtExt::predicate_must_hold_modulo_regions
+    /// [`Binder`]: ty::Binder
     #[instrument(level = "debug", skip(self, params), ret)]
     fn type_implements_trait(
         &self,