From 27dad009c61e6a21fc7cb438a08597cf0ec0b1c8 Mon Sep 17 00:00:00 2001
From: Nicholas Nethercote <n.nethercote@gmail.com>
Date: Thu, 3 Oct 2024 09:25:41 +1000
Subject: [PATCH] Add a useful comment about `InferOk`.

Prompted by #131134, which tried to remove `InferOk<'tcx, ()>`
occurrences.
---
 compiler/rustc_infer/src/infer/mod.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/compiler/rustc_infer/src/infer/mod.rs b/compiler/rustc_infer/src/infer/mod.rs
index cb60d9f286b..29936fadc57 100644
--- a/compiler/rustc_infer/src/infer/mod.rs
+++ b/compiler/rustc_infer/src/infer/mod.rs
@@ -67,6 +67,13 @@
 pub(crate) mod snapshot;
 mod type_variable;
 
+/// `InferOk<'tcx, ()>` is used a lot. It may seem like a useless wrapper
+/// around `Vec<PredicateObligation<'tcx>>`, but it has one important property:
+/// because `InferOk` is marked with `#[must_use]`, if you have a method
+/// `InferCtxt::f` that returns `InferResult<'tcx, ()>` and you call it with
+/// `infcx.f()?;` you'll get a warning about the obligations being discarded
+/// without use, which is probably unintentional and has been a source of bugs
+/// in the past.
 #[must_use]
 #[derive(Debug)]
 pub struct InferOk<'tcx, T> {