Update docs.

Author: cjgillot

compiler/rustc_mir_transform/src/elaborate_drop.rs

@@ -199,13 +199,30 @@ where
         self.elaborator.tcx()
     }
 
-    /// Generates three blocks:
-    /// * #1:pin_obj_bb:   call Pin<ObjTy>::new_unchecked(&mut obj)
-    /// * #2:call_drop_bb: fut = call obj.<AsyncDrop::drop>() OR call async_drop_in_place<T>(obj)
-    /// * #3:drop_term_bb: drop (obj, fut, ...)
-    /// We keep async drop unexpanded to poll-loop here, to expand it later, at StateTransform -
-    ///   into states expand.
-    /// call_destructor_only - to call only AsyncDrop::drop, not full async_drop_in_place glue
+    /// Async-drop `place: drop_ty`.
+    ///
+    /// Conceptually, we want to run `async_drop_in_place(&mut obj).await`.
+    ///
+    /// Await syntax does not exist in MIR, so we need to manually expand it into a poll-yield
+    /// loop, essentially:
+    /// ```mir
+    ///   let fut = async_drop_in_place(&mut obj);
+    ///   loop {
+    ///     let pin_fut = Pin::new_unchecked(&mut fut);
+    ///     match Future::poll(pin_fut, CTX_ARG) {
+    ///       Poll::Ready => break,
+    ///       Poll:Pending(..) => CTX_ARG = yield (),
+    ///     }
+    ///   }
+    ///   // continue to `succ`
+    /// ```
+    ///
+    /// We also need to ensure that async drop also happens on the coroutine drop path, ie. when
+    /// `yield` branches along its `drop` target. This requires a second loop, this time jumping to
+    /// `dropline`.
+    ///
+    /// Arguments:
+    ///   `call_destructor_only`: call only `AsyncDrop::drop`, not full `async_drop_in_place` glue
     #[instrument(level = "debug", skip(self), ret)]
     fn build_async_drop(
         &mut self,
@@ -336,8 +353,8 @@ where
         };
 
         // #2:call_drop_bb >>>
-        //    `call AsyncDrop::drop(pin_obj)`
-        // OR `call async_drop_in_place(pin_obj.pointer)`
+        //    call AsyncDrop::drop(pin_obj)
+        // OR call async_drop_in_place(pin_obj.pointer)
         let pin_adt_def = tcx.adt_def(tcx.require_lang_item(LangItem::Pin, span));
         let pin_obj_ty = Ty::new_adt(tcx, pin_adt_def, tcx.mk_args(&[obj_ref_ty.into()]));
         // Where we store the result of Pin<&drop_ty>::new_unchecked(&mut place).
@@ -424,18 +441,17 @@ where
     /// the future returns `Poll::Pending` and continuing to `ready_target`
     /// when it returns `Poll::Ready`.
     ///
-    /// The generated sequence:
-    /// - stores the `resume_arg_source` into a temporary context value;
-    /// - constructs a pinned reference to `fut_place` using `Pin::new_unchecked`;
-    /// - calls the future's `poll` function with the pinned future and the context reference;
-    /// - switches on the `Poll` discriminant: on `Ready` jump to
-    ///   `ready_target`, on `Pending` emit a `Yield` with `yield_value` that
-    ///   resumes back into the poll loop.
+    /// Pseudo-code:
+    /// ```mir
+    /// pin_bb:
+    ///   let pin_fut = Pin::new_unchecked(&mut fut_place);
+    ///   match Future::poll(pin_fut, CTX_ARG) {
+    ///     Poll::Ready => goto succ,
+    ///     Poll::Pending(..) => CTX_ARG = yield () [resume: resume_bb, drop: drop_bb],
+    ///   }
+    /// ```
     ///
-    ///  Returns:
-    ///  - the entry block (the pin-future block),
-    ///  - the yield resume block,
-    ///  - the drop resume block.
+    ///  Returns: the tuple `(pin_bb, resume_bb, drop_bb)`.
     #[instrument(level = "trace", skip(self), ret)]
     fn build_pin_poll_yield_loop(
         &mut self,