Properly document lifetime_mapping in OpaqueTy

compiler/rustc_ast_lowering/src/lib.rs

@@ -1619,13 +1619,15 @@ fn lower_opaque_impl_trait(
                 debug!(?hir_bounds);
 
                 let lifetime_mapping = if in_trait {
-                    self.arena.alloc_from_iter(
-                        collected_lifetime_mapping
-                            .iter()
-                            .map(|(lifetime, def_id)| (**lifetime, *def_id)),
+                    Some(
+                        &*self.arena.alloc_from_iter(
+                            collected_lifetime_mapping
+                                .iter()
+                                .map(|(lifetime, def_id)| (**lifetime, *def_id)),
+                        ),
                     )
                 } else {
-                    &mut []
+                    None
                 };
 
                 let opaque_ty_item = hir::OpaqueTy {
@@ -2090,13 +2092,15 @@ fn lower_async_fn_ret_ty(
                 debug!("lower_async_fn_ret_ty: generic_params={:#?}", generic_params);
 
                 let lifetime_mapping = if in_trait {
-                    self.arena.alloc_from_iter(
-                        collected_lifetime_mapping
-                            .iter()
-                            .map(|(lifetime, def_id)| (**lifetime, *def_id)),
+                    Some(
+                        &*self.arena.alloc_from_iter(
+                            collected_lifetime_mapping
+                                .iter()
+                                .map(|(lifetime, def_id)| (**lifetime, *def_id)),
+                        ),
                     )
                 } else {
-                    &mut []
+                    None
                 };
 
                 let opaque_ty_item = hir::OpaqueTy {

compiler/rustc_hir/src/hir.rs

@@ -2664,10 +2664,19 @@ pub struct OpaqueTy<'hir> {
     pub generics: &'hir Generics<'hir>,
     pub bounds: GenericBounds<'hir>,
     pub origin: OpaqueTyOrigin,
-    // Opaques have duplicated lifetimes, this mapping connects the original lifetime with the copy
-    // so we can later generate bidirectional outlives predicates to enforce that these lifetimes
-    // stay in sync.
-    pub lifetime_mapping: &'hir [(Lifetime, LocalDefId)],
+    /// Return-position impl traits (and async futures) must "reify" any late-bound
+    /// lifetimes that are captured from the function signature they originate from.
+    ///
+    /// This is done by generating a new early-bound lifetime parameter local to the
+    /// opaque which is substituted in the function signature with the late-bound
+    /// lifetime.
+    ///
+    /// This mapping associated a captured lifetime (first parameter) with the new
+    /// early-bound lifetime that was generated for the opaque.
+    pub lifetime_mapping: Option<&'hir [(Lifetime, LocalDefId)]>,
+    /// Whether the opaque is a return-position impl trait (or async future)
+    /// originating from a trait method. This makes it so that the opaque is
+    /// lowered as an associated type.
     pub in_trait: bool,
 }
 

compiler/rustc_hir_analysis/src/collect/predicates_of.rs

@@ -66,7 +66,7 @@ fn gather_explicit_predicates_of(tcx: TyCtxt<'_>, def_id: LocalDefId) -> ty::Gen
             let opaque_ty_id = tcx.hir().local_def_id_to_hir_id(opaque_def_id.expect_local());
             let opaque_ty_node = tcx.hir().get(opaque_ty_id);
             let Node::Item(&Item {
-                kind: ItemKind::OpaqueTy(OpaqueTy { lifetime_mapping, .. }),
+                kind: ItemKind::OpaqueTy(OpaqueTy { lifetime_mapping: Some(lifetime_mapping), .. }),
                 ..
             }) = opaque_ty_node
             else {