Bless tests, add comments

compiler/rustc_borrowck/src/type_check/input_output.rs

@@ -47,8 +47,9 @@ impl<'a, 'tcx> TypeChecker<'a, 'tcx> {
             user_provided_sig,
         );
 
-        // FIXME(async_closures): We must apply the same transformation to our
-        // signature here as we do during closure checking.
+        // FIXME(async_closures): It's kind of wacky that we must apply this
+        // transofmration here, since we do the same thing in HIR typeck.
+        // Maybe we could just fix up the canonicalized signature during HIR typeck?
         if let DefiningTy::CoroutineClosure(_, args) =
             self.borrowck_context.universal_regions.defining_ty
         {

compiler/rustc_borrowck/src/universal_regions.rs

@@ -98,7 +98,10 @@ pub enum DefiningTy<'tcx> {
     Coroutine(DefId, GenericArgsRef<'tcx>),
 
     /// The MIR is a special kind of closure that returns coroutines.
-    /// TODO: describe how to make the sig...
+    ///
+    /// See the documentation on `CoroutineClosureSignature` for details
+    /// on how to construct the callable signature of the coroutine from
+    /// its args.
     CoroutineClosure(DefId, GenericArgsRef<'tcx>),
 
     /// The MIR is a fn item with the given `DefId` and args. The signature

compiler/rustc_hir_typeck/src/fn_ctxt/checks.rs

@@ -333,7 +333,7 @@ impl<'a, 'tcx> FnCtxt<'a, 'tcx> {
                     continue;
                 }
 
-                // For this check, we do *not* want to treat async coroutine closures (async blocks)
+                // For this check, we do *not* want to treat async coroutine-closures (async blocks)
                 // as proper closures. Doing so would regress type inference when feeding
                 // the return value of an argument-position async block to an argument-position
                 // closure wrapped in a block.

compiler/rustc_middle/src/mir/mod.rs

@@ -260,8 +260,16 @@ pub struct CoroutineInfo<'tcx> {
     /// Coroutine drop glue. This field is populated after the state transform pass.
     pub coroutine_drop: Option<Body<'tcx>>,
 
-    /// The body of the coroutine, modified to take its upvars by move.
-    /// TODO:
+    /// The body of the coroutine, modified to take its upvars by move rather than by ref.
+    ///
+    /// This is used by coroutine-closures, which must return a different flavor of coroutine
+    /// when called using `AsyncFnOnce::call_once`. It is produced by the `ByMoveBody` which
+    /// is run right after building the initial MIR, and will only be populated for coroutines
+    /// which come out of the async closure desugaring.
+    ///
+    /// This body should be processed in lockstep with the containing body -- any optimization
+    /// passes, etc, should be applied to this body as well. This is done automatically if
+    /// using `run_passes`.
     pub by_move_body: Option<Body<'tcx>>,
 
     /// The layout of a coroutine. This field is populated after the state transform pass.

compiler/rustc_middle/src/query/mod.rs

@@ -756,7 +756,7 @@ rustc_queries! {
     }
 
     query coroutine_for_closure(def_id: DefId) -> DefId {
-        desc { |_tcx| "TODO" }
+        desc { |_tcx| "Given a coroutine-closure def id, return the def id of the coroutine returned by it" }
         separate_provide_extern
     }
 

compiler/rustc_middle/src/traits/select.rs

@@ -138,7 +138,9 @@ pub enum SelectionCandidate<'tcx> {
     /// generated for an `async ||` expression.
     AsyncClosureCandidate,
 
-    // TODO:
+    /// Implementation of the the `AsyncFnKindHelper` helper trait, which
+    /// is used internally to delay computation for async closures until after
+    /// upvar analysis is performed in HIR typeck.
     AsyncFnKindHelperCandidate,
 
     /// Implementation of a `Coroutine` trait by one of the anonymous types

compiler/rustc_middle/src/ty/instance.rs

@@ -101,7 +101,10 @@ pub enum InstanceDef<'tcx> {
         target_kind: ty::ClosureKind,
     },
 
-    /// TODO:
+    /// `<[coroutine] as Future>::poll`, but for coroutines produced when `AsyncFnOnce`
+    /// is called on a coroutine-closure whose closure kind is not `FnOnce`. This
+    /// will select the body that is produced by the `ByMoveBody` transform, and thus
+    /// take and use all of its upvars by-move rather than by-ref.
     CoroutineByMoveShim { coroutine_def_id: DefId },
 
     /// Compiler-generated accessor for thread locals which returns a reference to the thread local

compiler/rustc_middle/src/ty/print/pretty.rs

@@ -877,7 +877,7 @@ pub trait PrettyPrinter<'tcx>: Printer<'tcx> + fmt::Write {
             ty::CoroutineClosure(did, args) => {
                 p!(write("{{"));
                 if !self.should_print_verbose() {
-                    p!(write("coroutine closure"));
+                    p!(write("coroutine-closure"));
                     // FIXME(eddyb) should use `def_span`.
                     if let Some(did) = did.as_local() {
                         if self.tcx().sess.opts.unstable_opts.span_free_formats {

compiler/rustc_middle/src/ty/sty.rs

@@ -352,11 +352,31 @@ pub struct CoroutineClosureArgs<'tcx> {
 }
 
 pub struct CoroutineClosureArgsParts<'tcx> {
+    /// This is the args of the typeck root.
     pub parent_args: &'tcx [GenericArg<'tcx>],
+    /// Represents the maximum calling capability of the closure.
     pub closure_kind_ty: Ty<'tcx>,
+    /// Represents all of the relevant parts of the coroutine returned by this
+    /// coroutine-closure. This signature parts type will have the general
+    /// shape of `fn(tupled_inputs, resume_ty) -> (return_ty, yield_ty)`, where
+    /// `resume_ty`, `return_ty`, and `yield_ty` are the respective types for the
+    /// coroutine returned by the coroutine-closure.
+    ///
+    /// Use `coroutine_closure_sig` to break up this type rather than using it
+    /// yourself.
     pub signature_parts_ty: Ty<'tcx>,
+    /// The upvars captured by the closure. Remains an inference variable
+    /// until the upvar analysis, which happens late in HIR typeck.
     pub tupled_upvars_ty: Ty<'tcx>,
+    /// a function pointer that has the shape `for<'env> fn() -> (&'env T, ...)`.
+    /// This allows us to represent the binder of the self-captures of the closure.
+    ///
+    /// For example, if the coroutine returned by the closure borrows `String`
+    /// from the closure's upvars, this will be `for<'env> fn() -> (&'env String,)`,
+    /// while the `tupled_upvars_ty`, representing the by-move version of the same
+    /// captures, will be `(String,)`.
     pub coroutine_captures_by_ref_ty: Ty<'tcx>,
+    /// Witness type returned by the generator produced by this coroutine-closure.
     pub coroutine_witness_ty: Ty<'tcx>,
 }
 
@@ -572,15 +592,27 @@ pub struct CoroutineArgs<'tcx> {
 pub struct CoroutineArgsParts<'tcx> {
     /// This is the args of the typeck root.
     pub parent_args: &'tcx [GenericArg<'tcx>],
-    // TODO: why
+
+    /// The coroutines returned by a coroutine-closure's `AsyncFnOnce`/`AsyncFnMut`
+    /// implementations must be distinguished since the former takes the closure's
+    /// upvars by move, and the latter takes the closure's upvars by ref.
+    ///
+    /// This field distinguishes these fields so that codegen can select the right
+    /// body for the coroutine. This has the same type representation as the closure
+    /// kind: `i8`/`i16`/`i32`.
+    ///
+    /// For regular coroutines, this field will always just be `()`.
     pub kind_ty: Ty<'tcx>,
+
     pub resume_ty: Ty<'tcx>,
     pub yield_ty: Ty<'tcx>,
     pub return_ty: Ty<'tcx>,
+
     /// The interior type of the coroutine.
     /// Represents all types that are stored in locals
     /// in the coroutine's body.
     pub witness: Ty<'tcx>,
+
     /// The upvars captured by the closure. Remains an inference variable
     /// until the upvar analysis, which happens late in HIR typeck.
     pub tupled_upvars_ty: Ty<'tcx>,
@@ -632,7 +664,7 @@ impl<'tcx> CoroutineArgs<'tcx> {
         self.split().parent_args
     }
 
-    // TODO:
+    // Returns the kind of the coroutine. See docs on the `kind_ty` field.
     pub fn kind_ty(self) -> Ty<'tcx> {
         self.split().kind_ty
     }

compiler/rustc_mir_transform/src/const_prop_lint.rs

@@ -607,7 +607,8 @@ impl<'mir, 'tcx> ConstPropagator<'mir, 'tcx> {
                     AggregateKind::Array(_)
                     | AggregateKind::Tuple
                     | AggregateKind::Closure(_, _)
-                    | AggregateKind::Coroutine(_, _) => VariantIdx::new(0),
+                    | AggregateKind::Coroutine(_, _)
+                    | AggregateKind::CoroutineClosure(_, _) => VariantIdx::new(0),
                 },
             },
 

compiler/rustc_smir/src/rustc_smir/convert/mir.rs

@@ -539,7 +539,7 @@ impl<'tcx> Stable<'tcx> for mir::AggregateKind<'tcx> {
                 )
             }
             mir::AggregateKind::CoroutineClosure(..) => {
-                todo!("FIXME(async_closure): Lower these to SMIR")
+                todo!("FIXME(async_closures): Lower these to SMIR")
             }
         }
     }

compiler/rustc_smir/src/rustc_smir/convert/ty.rs

@@ -384,7 +384,7 @@ impl<'tcx> Stable<'tcx> for ty::TyKind<'tcx> {
                 tables.closure_def(*def_id),
                 generic_args.stable(tables),
             )),
-            ty::CoroutineClosure(..) => todo!("/* TODO */"),
+            ty::CoroutineClosure(..) => todo!("FIXME(async_closures): Lower these to SMIR"),
             ty::Coroutine(def_id, generic_args) => TyKind::RigidTy(RigidTy::Coroutine(
                 tables.coroutine_def(*def_id),
                 generic_args.stable(tables),

compiler/rustc_span/src/symbol.rs

@@ -331,6 +331,7 @@ symbols! {
         TyCtxt,
         TyKind,
         Unknown,
+        Upvars,
         Vec,
         VecDeque,
         Wrapper,

compiler/rustc_trait_selection/src/solve/assembly/mod.rs

@@ -190,7 +190,9 @@ pub(super) trait GoalKind<'tcx>:
         kind: ty::ClosureKind,
     ) -> QueryResult<'tcx>;
 
-    /// TODO:
+    /// Compute the built-in logic of the `AsyncFnKindHelper` helper trait, which
+    /// is used internally to delay computation for async closures until after
+    /// upvar analysis is performed in HIR typeck.
     fn consider_builtin_async_fn_kind_helper_candidate(
         ecx: &mut EvalCtxt<'_, 'tcx>,
         goal: Goal<'tcx, Self>,

compiler/rustc_trait_selection/src/solve/assembly/structural_traits.rs

@@ -8,6 +8,7 @@ use rustc_middle::traits::solve::Goal;
 use rustc_middle::ty::{
     self, ToPredicate, Ty, TyCtxt, TypeFoldable, TypeFolder, TypeSuperFoldable, TypeVisitableExt,
 };
+use rustc_span::sym;
 
 use crate::solve::EvalCtxt;
 
@@ -274,7 +275,7 @@ pub(in crate::solve) fn extract_tupled_inputs_and_output_from_callable<'tcx>(
             Ok(Some(closure_args.sig().map_bound(|sig| (sig.inputs()[0], sig.output()))))
         }
 
-        // Coroutine closures don't implement `Fn` traits the normal way.
+        // Coroutine-closures don't implement `Fn` traits the normal way.
         ty::CoroutineClosure(..) => Err(NoSolution),
 
         ty::Bool
@@ -341,11 +342,11 @@ pub(in crate::solve) fn extract_tupled_inputs_and_output_from_async_callable<'tc
                     vec![],
                 ))
             } else {
-                let helper_trait_def_id = tcx.require_lang_item(LangItem::AsyncFnKindHelper, None);
-                // FIXME(async_closures): Make this into a lang item.
+                let async_fn_kind_trait_def_id =
+                    tcx.require_lang_item(LangItem::AsyncFnKindHelper, None);
                 let upvars_projection_def_id = tcx
-                    .associated_items(helper_trait_def_id)
-                    .in_definition_order()
+                    .associated_items(async_fn_kind_trait_def_id)
+                    .filter_by_name_unhygienic(sym::Upvars)
                     .next()
                     .unwrap()
                     .def_id;
@@ -375,7 +376,7 @@ pub(in crate::solve) fn extract_tupled_inputs_and_output_from_async_callable<'tc
                     vec![
                         ty::TraitRef::new(
                             tcx,
-                            helper_trait_def_id,
+                            async_fn_kind_trait_def_id,
                             [kind_ty, Ty::from_closure_kind(tcx, goal_kind)],
                         )
                         .to_predicate(tcx),

compiler/rustc_trait_selection/src/traits/project.rs

@@ -2461,12 +2461,13 @@ fn confirm_async_closure_candidate<'cx, 'tcx>(
     let goal_kind =
         tcx.async_fn_trait_kind_from_def_id(obligation.predicate.trait_def_id(tcx)).unwrap();
 
-    let helper_trait_def_id = tcx.require_lang_item(LangItem::AsyncFnKindHelper, None);
+    let async_fn_kind_helper_trait_def_id =
+        tcx.require_lang_item(LangItem::AsyncFnKindHelper, None);
     nested.push(obligation.with(
         tcx,
         ty::TraitRef::new(
             tcx,
-            helper_trait_def_id,
+            async_fn_kind_helper_trait_def_id,
             [kind_ty, Ty::from_closure_kind(tcx, goal_kind)],
         ),
     ));
@@ -2476,9 +2477,12 @@ fn confirm_async_closure_candidate<'cx, 'tcx>(
         ty::ClosureKind::FnOnce => tcx.lifetimes.re_static,
     };
 
-    // FIXME(async_closures): Make this into a lang item.
-    let upvars_projection_def_id =
-        tcx.associated_items(helper_trait_def_id).in_definition_order().next().unwrap().def_id;
+    let upvars_projection_def_id = tcx
+        .associated_items(async_fn_kind_helper_trait_def_id)
+        .filter_by_name_unhygienic(sym::Upvars)
+        .next()
+        .unwrap()
+        .def_id;
 
     // FIXME(async_closures): Confirmation is kind of a mess here. Ideally,
     // we'd short-circuit when we know that the goal_kind >= closure_kind, and not

compiler/rustc_type_ir/src/ty_kind.rs

@@ -202,7 +202,11 @@ pub enum TyKind<I: Interner> {
     /// `ClosureArgs` for more details.
     Closure(I::DefId, I::GenericArgs),
 
-    /// TODO
+    /// The anonymous type of a closure. Used to represent the type of `async |a| a`.
+    ///
+    /// Coroutine-closure args contain both the - potentially substituted - generic
+    /// parameters of its parent and some synthetic parameters. See the documentation
+    /// for `CoroutineClosureArgs` for more details.
     CoroutineClosure(I::DefId, I::GenericArgs),
 
     /// The anonymous type of a coroutine. Used to represent the type of

library/core/src/ops/async_function.rs

@@ -108,9 +108,26 @@ mod impls {
 }
 
 mod internal_implementation_detail {
-    // TODO: needs a detailed explanation
+    /// A helper trait that is used to enforce that the `ClosureKind` of a goal
+    /// is within the capabilities of a `CoroutineClosure`, and which allows us
+    /// to delay the projection of the tupled upvar types until after upvar
+    /// analysis is complete.
+    ///
+    /// The `Self` type is expected to be the `kind_ty` of the coroutine-closure,
+    /// and thus either `?0` or `i8`/`i16`/`i32` (see docs for `ClosureKind`
+    /// for an explanation of that). The `GoalKind` is also the same type, but
+    /// representing the kind of the trait that the closure is being called with.
     #[cfg_attr(not(bootstrap), lang = "async_fn_kind_helper")]
     trait AsyncFnKindHelper<GoalKind> {
-        type Assoc<'closure_env, Inputs, Upvars, BorrowedUpvarsAsFnPtr>;
+        // Projects a set of closure inputs (arguments), a region, and a set of upvars
+        // (by move and by ref) to the upvars that we expect the coroutine to have
+        // according to the `GoalKind` parameter above.
+        //
+        // The `Upvars` parameter should be the upvars of the parent coroutine-closure,
+        // and the `BorrowedUpvarsAsFnPtr` will be a function pointer that has the shape
+        // `for<'env> fn() -> (&'env T, ...)`. This allows us to represent the binder
+        // of the closure's self-capture, and these upvar types will be instantiated with
+        // the `'closure_env` region provided to the associated type.
+        type Upvars<'closure_env, Inputs, Upvars, BorrowedUpvarsAsFnPtr>;
     }
 }

tests/ui/async-await/async-borrowck-escaping-closure-error.rs

@@ -1,10 +1,11 @@
 // edition:2018
-// check-pass
 
 #![feature(async_closure)]
 fn foo() -> Box<dyn std::future::Future<Output = u32>> {
     let x = 0u32;
     Box::new((async || x)())
+    //~^ ERROR cannot return value referencing local variable `x`
+    //~| ERROR cannot return value referencing temporary value
 }
 
 fn main() {

tests/ui/async-await/async-borrowck-escaping-closure-error.stderr

@@ -0,0 +1,21 @@
+error[E0515]: cannot return value referencing local variable `x`
+  --> $DIR/async-borrowck-escaping-closure-error.rs:6:5
+   |
+LL |     Box::new((async || x)())
+   |     ^^^^^^^^^------------^^^
+   |     |        |
+   |     |        `x` is borrowed here
+   |     returns a value referencing data owned by the current function
+
+error[E0515]: cannot return value referencing temporary value
+  --> $DIR/async-borrowck-escaping-closure-error.rs:6:5
+   |
+LL |     Box::new((async || x)())
+   |     ^^^^^^^^^------------^^^
+   |     |        |
+   |     |        temporary value created here
+   |     returns a value referencing data owned by the current function
+
+error: aborting due to 2 previous errors
+
+For more information about this error, try `rustc --explain E0515`.

tests/ui/async-await/async-closures/higher-ranked.rs

@@ -1,12 +1,10 @@
 // edition:2021
+// check-pass
 
 #![feature(async_closure)]
 
 fn main() {
     let x = async move |x: &str| {
-        //~^ ERROR lifetime may not live long enough
-        // This error is proof that the `&str` type is higher-ranked.
-        // This won't work until async closures are fully impl'd.
         println!("{x}");
     };
 }