From 9f03a2ba821a6342e951d583cc69fa9b51b1f2f6 Mon Sep 17 00:00:00 2001
From: Michael Goulet <michael@errs.io>
Date: Tue, 19 Mar 2024 12:55:26 -0400
Subject: [PATCH] Add a few more comments

---
 compiler/rustc_middle/src/ty/instance.rs | 2 +-
 compiler/rustc_middle/src/ty/sty.rs      | 4 ++++
 compiler/rustc_mir_transform/src/shim.rs | 9 +++++++++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/compiler/rustc_middle/src/ty/instance.rs b/compiler/rustc_middle/src/ty/instance.rs
index 18ef4ed549b4c..4748e961019e1 100644
--- a/compiler/rustc_middle/src/ty/instance.rs
+++ b/compiler/rustc_middle/src/ty/instance.rs
@@ -101,7 +101,7 @@ pub enum InstanceDef<'tcx> {
         // because the signature of `<{async fn} as FnMut>::call_mut` is:
         // `fn(&mut self, args: A) -> <Self as FnOnce>::Output`, that is to say
         // that it returns the `FnOnce`-flavored coroutine but takes the closure
-        // by ref (and similarly for `Fn::call`).
+        // by mut ref (and similarly for `Fn::call`).
         receiver_by_ref: bool,
     },
 
diff --git a/compiler/rustc_middle/src/ty/sty.rs b/compiler/rustc_middle/src/ty/sty.rs
index 6790801304121..6e0a9eb86dde7 100644
--- a/compiler/rustc_middle/src/ty/sty.rs
+++ b/compiler/rustc_middle/src/ty/sty.rs
@@ -2461,6 +2461,10 @@ impl<'tcx> Ty<'tcx> {
     /// `AsyncFn`/`AsyncFnMut`/`AsyncFnOnce`, we only need to distinguish two coroutine
     /// bodies: by-ref and by-value.
     ///
+    /// See the definition of `AsyncFn` and `AsyncFnMut` and the `CallRefFuture`
+    /// associated type for why we don't distinguish [`ty::ClosureKind::Fn`] and
+    /// [`ty::ClosureKind::FnMut`] for the purpose of the generated MIR bodies.
+    ///
     /// This method should be used when constructing a `Coroutine` out of a
     /// `CoroutineClosure`, when the `Coroutine`'s `kind` field is being populated
     /// directly from the `CoroutineClosure`'s `kind`.
diff --git a/compiler/rustc_mir_transform/src/shim.rs b/compiler/rustc_mir_transform/src/shim.rs
index 4b2243598dc1d..28b502e8cabe5 100644
--- a/compiler/rustc_mir_transform/src/shim.rs
+++ b/compiler/rustc_mir_transform/src/shim.rs
@@ -1023,7 +1023,16 @@ fn build_construct_coroutine_by_move_shim<'tcx>(
         bug!();
     };
 
+    // We use `*mut Self` here because we only need to emit an ABI-compatible shim body,
+    // rather than match the signature exactly.
+    //
+    // The self type here is a coroutine-closure, not a coroutine, and we never read from
+    // it because it never has any captures, because this is only true in the Fn/FnMut
+    // implementation, not the AsyncFn/AsyncFnMut implementation, which is implemented only
+    // if the coroutine-closure has no captures.
     if receiver_by_ref {
+        // Triple-check that there's no captures here.
+        assert_eq!(args.as_coroutine_closure().tupled_upvars_ty(), tcx.types.unit);
         self_ty = Ty::new_mut_ptr(tcx, self_ty);
     }